{"_id":"@aid-system/sdk","name":"@aid-system/sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aid-system/sdk","version":"0.1.0","description":"TypeScript SDK for Agent_ID_Card","license":"UNLICENSED","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"publishConfig":{"access":"public"},"sideEffects":false,"scripts":{"build":"tsc","dev":"tsc --watch","clean":"rm -rf dist","test":"npm run build && node --test test/*.test.mjs","pack:dry-run":"npm run build && npm pack --dry-run"},"devDependencies":{"typescript":"^5.4.0"},"engines":{"node":">=20.9.0"},"gitHead":"1e1780eb51bc750cb49ed64cc8bcb511482b6145","_id":"@aid-system/sdk@0.1.0","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-1hqMUWA6wxE5qS5SJUjOqNMjQHLuGsdoCfIoR5ISrAGTkWpmxU4XW2LO+zRjbWb1lvvzEOjt4Wpn8rMe19Xn+w==","shasum":"a57f2d3cef99540b8462bdb69947bd8ef53d6506","tarball":"https://registry.npmjs.org/@aid-system/sdk/-/sdk-0.1.0.tgz","fileCount":7,"unpackedSize":80570,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFSC1Y94ZtbfoZk9MWi6N35ioSfBOt0Zuhk624m4zhjmAiAkvjOb+Wt3PZtXenFVUH45NX0qTKqeaAAgDmdWrBjPgQ=="}]},"_npmUser":{"name":"deoluncen","email":"deoliste@gmail.com"},"directories":{},"maintainers":[{"name":"deoluncen","email":"deoliste@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.0_1783774002548_0.3809810194655201"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-11T12:46:42.285Z","0.1.0":"2026-07-11T12:46:42.739Z","modified":"2026-07-11T12:46:43.086Z"},"maintainers":[{"name":"deoluncen","email":"deoliste@gmail.com"}],"description":"TypeScript SDK for Agent_ID_Card","license":"UNLICENSED","readme":"# @aid-system/sdk\n\nTypeScript SDK for Agent_ID_Card.\n\n```text\nstatus: npm_publish_candidate\npublish_status: public_package_metadata_enabled\nwrite_methods: server_side_reportActivity\n```\n\n## Install\n\n```bash\nnpm install @aid-system/sdk\n```\n\n## Publish Readiness\n\nThe package is configured for public npm publication:\n\n- `publishConfig.access: public` keeps the scoped package public.\n- `files` limits package contents to `dist/`, `src/`, and `README.md`.\n- `exports` points consumers at the compiled entrypoint and declarations.\n- Public SDK response types are defined inside this package, so the candidate\n  package no longer depends on the unpublished workspace-only\n  `@aid-system/types` package.\n\nUse this local check only:\n\n```bash\nnpm run pack:dry-run -w packages/sdk\n```\n\nProduction write-token activation evidence now exists. Actual npm publish\nrequires npm organization ownership, npm account/2FA readiness, and final\npublish command evidence. The package remains `UNLICENSED` because the project\nroot declares a proprietary, all-rights-reserved license.\n\n## Usage\n\n```typescript\nimport { createAIDClient } from '@aid-system/sdk';\n\nconst client = createAIDClient({\n  baseUrl: 'https://agent-id-card-web.vercel.app',\n});\n\nconst aid = 'aid:global:agent:c595231a-012d-414e-8bfb-21096ce444af:5ca4';\nconst result = await client.getAgentInfo(aid);\n\nif (result.success) {\n  console.log(result.data.name);\n} else {\n  console.error(result.error?.code, result.error?.message);\n}\n```\n\n## Server-Side Activity Reporting\n\n`reportActivity` is a local candidate helper for server-side runtimes only. Do\nnot use Agent write tokens in browser bundles, local storage, mobile apps, or\npublic client-side code.\n\n```typescript\nimport { createAIDClient } from '@aid-system/sdk';\n\nconst client = createAIDClient({\n  baseUrl: 'https://agent-id-card-web.vercel.app',\n  writeToken: process.env.AID_AGENT_WRITE_TOKEN,\n});\n\nawait client.reportActivity({\n  aid: 'aid:global:agent:c595231a-012d-414e-8bfb-21096ce444af:5ca4',\n  success: true,\n  latencyMs: 123,\n  idempotencyKey: 'activity-20260528-0001',\n});\n```\n\n`apiKey` is accepted as a server-side alias for `writeToken` to support\nolder integration naming, but both options map to the same bearer credential.\nPrefer `writeToken` in new code.\n\n`reportActivity` validates inputs locally before sending a request:\n\n- The payload must only include `aid`, `success`, `latencyMs`, and\n  `idempotencyKey`; unsupported fields fail locally instead of being silently\n  dropped.\n- `aid` must match the `aid:global:agent:<uuid>:<checksum>` structure. The API\n  remains the checksum and authorization authority.\n- `success` must be a boolean.\n- `latencyMs` must be a non-negative integer.\n- `idempotencyKey` must be a string, must be 16-128 characters, must not\n  contain whitespace or control characters, and may use only letters, numbers,\n  `.`, `_`, `:`, or `-`.\n\nRead helpers also trim `aid` values before encoding. `getAgentInfo`,\n`getActivityStats`, and `getScore` reject malformed AIDs locally instead of\ncalling the network. `verifyAID` still forwards invalid-format candidates to\nthe registry so the server can return `valid: false`.\n\nClient configuration is also validated locally:\n\n- `baseUrl` must be a non-empty absolute `http(s)` URL and is trimmed before use.\n  Optional base paths are preserved, but credentials, query strings, fragments,\n  whitespace, and control characters are rejected.\n- `timeoutMs` must be a positive JavaScript safe integer no greater than\n  `2147483647`.\n- `writeToken` and `apiKey` are trimmed, must be non-empty strings when provided,\n  and must not contain whitespace or control characters.\n- `fetch` must be the correct runtime type when provided.\n- `listAgents()` and `getLeaderboard()` trim query strings and reject malformed\n  pagination values before calling the network.\n\n## Local Request Observability\n\n`onRequestEvent` can be provided for local server-side logging, metrics, or\ntest assertions:\n\n```typescript\nconst client = createAIDClient({\n  baseUrl: 'https://agent-id-card-web.vercel.app',\n  writeToken: process.env.AID_AGENT_WRITE_TOKEN,\n  onRequestEvent(event) {\n    console.log(event.type, event.method, event.path, event.status);\n  },\n});\n```\n\nThe callback is synchronous and local-only. It does not export telemetry or\ncontact any monitoring provider. Observer errors are swallowed so logging code\ncannot change SDK request results.\n\nRequest events are intentionally sanitized:\n\n- `request:start` includes only `type`, `method`, and URL `path`.\n- `request:success` adds `status` and `durationMs`.\n- `request:error` adds `status`, `durationMs`, and `errorCode`.\n- Events never include the full URL, query string, request headers, request\n  body, `Authorization` value, write token, `apiKey`, `Idempotency-Key`, DB URL,\n  environment value, or provider response body.\n- Local validation failures return before fetch and do not emit request events.\n\n## Local Request Metrics\n\n`createAIDRequestMetrics()` is a local in-process helper that consumes the same\nsanitized request events from `onRequestEvent` and returns aggregate snapshots:\n\n```typescript\nimport { createAIDClient, createAIDRequestMetrics } from '@aid-system/sdk';\n\nconst requestMetrics = createAIDRequestMetrics();\n\nconst client = createAIDClient({\n  baseUrl: 'https://agent-id-card-web.vercel.app',\n  writeToken: process.env.AID_AGENT_WRITE_TOKEN,\n  onRequestEvent: requestMetrics.onRequestEvent,\n});\n\nawait client.getScore('aid:global:agent:c595231a-012d-414e-8bfb-21096ce444af:5ca4');\n\nconsole.log(requestMetrics.snapshot());\n```\n\nSnapshots include total started/completed/succeeded/failed counts, in-flight\ncount, average and max duration, status-code counts, error-code counts, and\nper-route aggregates keyed by `METHOD /path`.\n\nThis helper is local-only. It does not export telemetry, retain credentials,\ncontact an external monitoring provider, configure alerts, start runtime\nsessions, or publish the SDK. Route keys use sanitized request paths only; they\nstill may include encoded AID path segments, so treat snapshots as local\nserver-side operational data rather than public client payloads.\n\n## API\n\n- `createAIDClient(options)`\n- `createAIDRequestMetrics()`\n- `listAgents(options)`\n- `getAgentInfo(aid)`\n- `getLeaderboard(options)`\n- `verifyAID(aid)`\n- `getActivityStats(aid)`\n- `getScore(aid)`\n- `reportActivity(input)` server-side candidate only\n\n## Boundaries\n\nThis SDK is distributed for server-side integrations and does not grant an\nopen-source license. The write helper depends on server-side token lifecycle\npolicy, human-retained operator-token rotation before future issuance, secret\nreview, and release evidence. It does not include:\n\n- API keys or token storage\n- token issuance, rotation, or revocation\n- browser-safe write credentials\n- automatic idempotency key generation\n- external telemetry export\n- official certification helpers\n\nWrite tokens must be provided by the server operator and are sent as\n`Authorization: Bearer <token>` with an `Idempotency-Key` header.\n","readmeFilename":"README.md","_rev":"1-a8098f1c31d38b560e7113ae746c2415"}