{"_id":"@semiotic-labs/agentium-sdk","_rev":"26-aa22915a9469a43e184ab780cf09c844","name":"@semiotic-labs/agentium-sdk","dist-tags":{"latest":"0.11.0"},"versions":{"0.1.0":{"name":"@semiotic-labs/agentium-sdk","version":"0.1.0","keywords":[],"author":"","license":"MIT","_id":"@semiotic-labs/agentium-sdk@0.1.0","maintainers":[{"name":"mconsoli","email":"consoli@semiotic.ai"},{"name":"suchapalaver","email":"joseph@semiotic.ai"},{"name":"anirudh-semiotic","email":"anirudh@semiotic.ai"}],"homepage":"https://github.com/semiotic-agentium/agentium-sdk#readme","bugs":{"url":"https://github.com/semiotic-agentium/agentium-sdk/issues"},"dist":{"shasum":"41fa65fa861b8256ae02324b3f007a05ff8ea765","tarball":"https://registry.npmjs.org/@semiotic-labs/agentium-sdk/-/agentium-sdk-0.1.0.tgz","fileCount":3,"integrity":"sha512-lwo+aIjAqv4qaogut7qWVElI+NQA5udH+omoje8x/Lu0j62HWIs5XmYIsnSaLfPJK8I2yM1jycwKfB/uQebCeA==","signatures":[{"sig":"MEUCICp4A+UqmYED6ZChlwDUKQRBGlffkjpi7JcXlB0kL4CnAiEAwSZkQEWKCWXFIOU9U00+UWI1b4DB5xi4MvJq6pG7Usk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1603},"main":"index.js","gitHead":"0b563c493aa69bd05eace72fd4f216a9648dfbae","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"anirudh-semiotic","email":"anirudh@semiotic.ai"},"repository":{"url":"git+https://github.com/semiotic-agentium/agentium-sdk.git","type":"git"},"_npmVersion":"10.9.4","description":"","directories":{},"_nodeVersion":"22.21.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/agentium-sdk_0.1.0_1764609754621_0.2318920353938425","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@semiotic-labs/agentium-sdk","version":"0.2.0","keywords":[],"author":"","license":"MIT","_id":"@semiotic-labs/agentium-sdk@0.2.0","maintainers":[{"name":"mconsoli","email":"consoli@semiotic.ai"},{"name":"suchapalaver","email":"joseph@semiotic.ai"},{"name":"anirudh-semiotic","email":"anirudh@semiotic.ai"},{"name":"semiotic-admin","email":"it-admin@semiotic.ai"},{"name":"natanael.semiotic","email":"natanael@semiotic.ai"}],"homepage":"https://github.com/semiotic-agentium/agentium-sdk#readme","bugs":{"url":"https://github.com/semiotic-agentium/agentium-sdk/issues"},"dist":{"shasum":"4e5815c6c9b31ef59457f64b4f55c1ecb6a9ed20","tarball":"https://registry.npmjs.org/@semiotic-labs/agentium-sdk/-/agentium-sdk-0.2.0.tgz","fileCount":3,"integrity":"sha512-cgJ23HCSSnN1n/TCk4UfIAUXTS2WHk+ueu4xQUD2xBsYN7WfjQpxC3Od8ea1xzlx9k+MzjHB/v2LujDmSYJSsw==","signatures":[{"sig":"MEYCIQCvwN+3M6kTGdOh1VQvXajo8Guu6SMLlbN20EHrCOXMsgIhAMrth5rtZq9wuL6+szZGqB2eYwrc9xwu5LHDf/z6YSdj","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4859},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=22.0.0"},"gitHead":"f5fbc9e1f765a8e0fe062cd69857b02c7967c941","scripts":{"docs":"typedoc","lint":"eslint src/**/*.ts","test":"vitest","build":"tsc","check":"npm run lint && npm run format:check","reuse:check":"reuse lint","reuse:write":"reuse annotate --license MIT --copyright \"Semiotic AI, Inc.\" --year 2025 -r . --fallback-dot-license --skip-existing","format:check":"prettier --check .","format:write":"prettier --write ."},"_npmUser":{"name":"anirudh-semiotic","email":"anirudh@semiotic.ai"},"repository":{"url":"git+https://github.com/semiotic-agentium/agentium-sdk.git","type":"git"},"_npmVersion":"10.9.4","description":"\n\n# @semiotic-labs/agentium-sdk\n\nTypeScript SDK for interacting with the Agentium Network API. Supports identity connection, OAuth token management, and W3C Verifiable Credentials (VCs) with Ed25519 signatures.\n\n## Installation\n\n```bash\nnpm install @semiotic-labs/agentium-sdk\n```\n\n## Quick Start\n\n```typescript\nimport { AgentiumClient } from '@semiotic-labs/agentium-sdk';\n\nconst client = new AgentiumClient();\n\n// Connect with Google identity\nconst response = await client.connectGoogleIdentity(googleJwtToken);\nconsole.log('User DID:', response.did);\nconsole.log('Access Token:', response.accessToken);\n```\n\n## API Reference\n\n### Client Setup\n\n```typescript\nimport { AgentiumClient } from '@semiotic-labs/agentium-sdk';\n\n// Default: https://api.agentium.network\nconst client = new AgentiumClient();\n\n// Custom endpoint (for local/staging)\nconst client = new AgentiumClient({ baseURL: 'http://localhost:8080' });\n\n// For bundlers like Vite that require explicit WASM URL\nimport wasmUrl from '@semiotic-labs/agentium-sdk/wasm?url';\nconst client = new AgentiumClient({ wasmUrl });\n```\n\n### Identity Connection\n\n#### `connectGoogleIdentity(googleToken, options?)`\n\nConnects a Google identity to an Agentium identity.\n\n```typescript\n// Standard Google Sign-In\nconst response = await client.connectGoogleIdentity(googleJwtToken);\n\n// External OAuth (e.g., zkLogin) - skip audience validation\nconst response = await client.connectGoogleIdentity(googleJwtToken, {\n skipAudienceValidation: true,\n});\n```\n\n**Returns:** `ConnectIdentityResponse` with `did`, `accessToken`, `refreshToken`, `expiresIn`, `isNew`, `badge`\n\n### Token Management\n\n#### `exchangeApiKey(apiKey)`\n\nExchanges an API key for JWT tokens (M2M authentication).\n\n```typescript\nconst tokens = await client.exchangeApiKey('ak_your_api_key');\n```\n\n#### `refreshToken(refreshTokenValue)`\n\nRefreshes an access token using a refresh token.\n\n```typescript\nconst newTokens = await client.refreshToken(currentRefreshToken);\n```\n\n### Verifiable Credentials\n\nThe SDK supports W3C Verifiable Credentials issued as JWTs with Ed25519 signatures.\n\n#### Storage Setup\n\n```typescript\nimport { createBrowserStorage, createMemoryStorage } from '@semiotic-labs/agentium-sdk';\n\n// Browser environment (uses localStorage)\nclient.setVcStorage(createBrowserStorage());\n\n// Node.js or testing (in-memory)\nclient.setVcStorage(createMemoryStorage());\n```\n\n#### `fetchMembershipCredential(token)`\n\nFetches a membership credential from the backend.\n\n```typescript\nconst vcJwt = await client.fetchMembershipCredential(authToken);\n```\n\n#### `verifyCredential(jwt)`\n\nVerifies a JWT-VC against the issuer's public key.\n\n```typescript\nconst result = await client.verifyCredential(vcJwt);\n\nif (result.valid) {\n console.log('Subject DID:', result.claims?.sub);\n} else {\n console.error('Error:', result.error?.code, result.error?.message);\n}\n```\n\n#### `connectAndStoreMembership(token)`\n\nFull flow: fetch, verify, and store a membership credential.\n\n```typescript\nconst result = await client.connectAndStoreMembership(authToken);\n```\n\n#### `getStoredCredential()`\n\nRetrieves the stored VC JWT from storage.\n\n```typescript\nconst storedVc = client.getStoredCredential();\n```\n\n### WASM Utilities\n\nLow-level cryptographic operations for Ed25519. WASM is automatically initialized on first use — no manual setup required.\n\n```typescript\nimport { verifyJwt, generateKeypair, getPublicKey } from '@semiotic-labs/agentium-sdk';\n\n// Generate key pair\nconst { privateKey, publicKey } = await generateKeypair();\n\n// Verify JWT directly\nconst result = await verifyJwt(jwtString, publicKeyJwk);\n```\n\n#### Bundler Configuration (Vite, etc.)\n\nFor bundlers like Vite that require explicit WASM URL resolution, pass `wasmUrl` to the client constructor (see [Client Setup](#client-setup)).\n\nIf using low-level WASM utilities directly (without `AgentiumClient`), initialize manually:\n\n```typescript\nimport { ensureWasmReady } from '@semiotic-labs/agentium-sdk';\nimport wasmUrl from '@semiotic-labs/agentium-sdk/wasm?url';\n\nawait ensureWasmReady(wasmUrl);\n```\n\n### Error Handling\n\nAll API methods throw `AgentiumApiError` on failure:\n\n```typescript\nimport { AgentiumApiError } from '@semiotic-labs/agentium-sdk';\n\ntry {\n await client.connectGoogleIdentity(token);\n} catch (error) {\n if (error instanceof AgentiumApiError) {\n console.error(`API Error (${error.statusCode}): ${error.message}`);\n }\n}\n```\n\n### Telemetry\n\nThe SDK provides a flexible telemetry system that forwards tracing events from the WASM layer to JavaScript. Consumers can define custom sinks to handle events (logging, analytics, monitoring services, etc.).\n\n> **Note:** The WASM layer currently emits events only — spans are not yet supported.\n\n#### Initialization\n\nTelemetry must be initialized after WASM is ready and can only be called once. If not initialized, no telemetry is emitted (silent by default).\n\n```typescript\nimport { ensureWasmReady, initTelemetry, consoleSink } from '@semiotic-labs/agentium-sdk';\n\nawait ensureWasmReady();\ninitTelemetry({ sink: consoleSink });\n```\n\n#### Built-in Sinks\n\n- **`consoleSink`** — Logs events to the browser/Node console using the appropriate method (`console.error`, `console.warn`, etc.)\n- **`nullSink`** — Discards all events (useful for explicitly disabling telemetry)\n\n#### Filtering Events\n\nFilter events by level or target module:\n\n```typescript\nimport { withLevelFilter, withTargetFilter, consoleSink } from '@semiotic-labs/agentium-sdk';\n\n// Only log errors and warnings\nconst errorSink = withLevelFilter(['error', 'warn'], consoleSink);\n\n// Only log events from agentium modules\nconst agentiumSink = withTargetFilter(['agentium_sdk'], consoleSink);\n```\n\n#### Composing Sinks\n\nCombine multiple sinks to forward events to different destinations:\n\n```typescript\nimport { composeSinks, withLevelFilter, consoleSink, initTelemetry } from '@semiotic-labs/agentium-sdk';\n\nconst myAnalyticsSink = (event) => {\n // Send to your analytics service\n analytics.track('sdk_event', event);\n};\n\ninitTelemetry({\n sink: composeSinks(\n withLevelFilter(['error', 'warn', 'info'], consoleSink),\n myAnalyticsSink\n ),\n filter: 'agentium_sdk=debug' // tracing-subscriber EnvFilter syntax\n});\n```\n\n#### Event Structure\n\nEvents passed to sinks have the following shape:\n\n```typescript\ninterface TelemetryEvent {\n kind: 'event'; // Event type (currently always \"event\")\n level: 'error' | 'warn' | 'info' | 'debug' | 'trace';\n target: string; // Module path (e.g., \"agentium_sdk_wasm::vc\")\n name?: string; // Event name\n fields: Record; // Structured fields from the event\n ts_ms: number; // Timestamp in milliseconds\n}\n```\n\n## API Documentation\n\nGenerate full API documentation from source:\n\n```bash\nnpm run docs\n```\n\nDocumentation is output to the `docs/` folder.\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/semiotic-agentium/agentium-sdk.git\ncd agentium-sdk\nnpm install\n```\n\n### Scripts\n\n```bash\nnpm test # Run tests\nnpm run build # Build (WASM + TypeScript)\nnpm run docs # Generate API docs\nnpm run lint # Lint code\nnpm run check # Lint + format check\nnpm run check:python # Type-check Python code (mypy)\nnpm run format:all # Format all code (TS, Python, Rust)\nnpm run format:rust # Format Rust code\n```\n\n### REUSE Compliance\n\nThis project follows the [REUSE Specification](https://reuse.software/spec/).\n\n```bash\npip install reuse # Install REUSE tool\nnpm run reuse:check # Verify compliance\nnpm run reuse:write # Apply SPDX headers\n```\n\n## Python SDK\n\nA Python SDK is also available with equivalent functionality. See the [Python SDK documentation](packages/agentium-native/python/README.md) for installation and usage.\n\n```bash\npip install agentium\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}