{"_id":"@digital-card-twin/sdk","_rev":"2-30305896ceac8e7e59567119890d719d","name":"@digital-card-twin/sdk","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@digital-card-twin/sdk","version":"0.1.0","_id":"@digital-card-twin/sdk@0.1.0","maintainers":[{"name":"lomalobiche","email":"engineering@digital-card-twin.com"}],"dist":{"shasum":"e256d0f89d6719d3fdbf0c7ff1ac4acbda1e9aa1","tarball":"https://registry.npmjs.org/@digital-card-twin/sdk/-/sdk-0.1.0.tgz","fileCount":18,"integrity":"sha512-XSYNB5pqh978BkBFXcUMLav+mOFakRlfNC4eW6W/9311d73sFSiXeFtPkvw4QNaBMGu94+Ni9xd2rtgVYnZ3eg==","signatures":[{"sig":"MEYCIQCaB8iDZ1wTLLtnIs/Ab1d60JRLBMATVsTEXOq20kh1ZwIhANWu3HNpgOXaGC5jIe9hy91HYya2Wm/wIBo1CsbwxQOF","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":75220},"main":"./dist/index.js","type":"module","_from":"file:digital-card-twin-sdk-0.1.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=22.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"lomalobiche","email":"engineering@digital-card-twin.com"},"_resolved":"/private/var/folders/17/vb44ykxn073bbdtj2dm6j1dw0000gq/T/57c2fc1b647c2c11b7c692e68963d2e3/digital-card-twin-sdk-0.1.0.tgz","_integrity":"sha512-XSYNB5pqh978BkBFXcUMLav+mOFakRlfNC4eW6W/9311d73sFSiXeFtPkvw4QNaBMGu94+Ni9xd2rtgVYnZ3eg==","_npmVersion":"11.6.1","description":"TypeScript client SDK for the digital-card-twin protocol — certificate lookup, metadata fetch, job polling, and submission","directories":{},"_nodeVersion":"24.11.0","dependencies":{"viem":"^2.17.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","vitest":"^1.5.0","typescript":"^5.4.0","@types/node":"^20.12.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1776637807107_0.9336630771293939","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@digital-card-twin/sdk","version":"0.1.1","publishConfig":{"access":"public"},"description":"TypeScript client SDK for the digital-card-twin protocol — certificate lookup, metadata fetch, job polling, and submission","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"dependencies":{"viem":"^2.17.0"},"devDependencies":{"@types/node":"^20.12.0","tsx":"^4.7.0","typescript":"^5.4.0","vitest":"^1.5.0"},"engines":{"node":">=22.0.0"},"scripts":{"build":"tsc","dev":"tsc --watch","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit"},"_id":"@digital-card-twin/sdk@0.1.1","_integrity":"sha512-fj2rqcHWdsArUY5lqPVsmQavkk7lJJQP1G1+QhDJL3pJ/BIEqy14et5xzx7XKuXsa8aWRrxT2Ev+m/NGpCHVBQ==","_resolved":"/private/var/folders/17/vb44ykxn073bbdtj2dm6j1dw0000gq/T/fb96d0013e1824550fd6ae3a78f23eb1/digital-card-twin-sdk-0.1.1.tgz","_from":"file:digital-card-twin-sdk-0.1.1.tgz","_nodeVersion":"24.11.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-fj2rqcHWdsArUY5lqPVsmQavkk7lJJQP1G1+QhDJL3pJ/BIEqy14et5xzx7XKuXsa8aWRrxT2Ev+m/NGpCHVBQ==","shasum":"cf1abc42fd668f5974858930ac5c4b08ba246696","tarball":"https://registry.npmjs.org/@digital-card-twin/sdk/-/sdk-0.1.1.tgz","fileCount":19,"unpackedSize":78538,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDSTN6HyWi7ChASlfVOtUG0kgOtUX+2m6sguXL7EI6iiwIgKkzC5GOV2k68+XpzpC6OcSdjv5I4sAsNFj3Qcdu6+/U="}]},"_npmUser":{"name":"lomalobiche","email":"engineering@digital-card-twin.com"},"directories":{},"maintainers":[{"name":"lomalobiche","email":"engineering@digital-card-twin.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.1_1776638025610_0.2753841242142987"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-19T22:30:07.045Z","modified":"2026-04-19T22:33:45.896Z","0.1.0":"2026-04-19T22:30:07.242Z","0.1.1":"2026-04-19T22:33:45.767Z"},"description":"TypeScript client SDK for the digital-card-twin protocol — certificate lookup, metadata fetch, job polling, and submission","maintainers":[{"name":"lomalobiche","email":"engineering@digital-card-twin.com"}],"readme":"# @digital-card-twin/sdk\n\nTypeScript client SDK for the **digital-card-twin** protocol — certificate lookup, NFT metadata fetch, and grading event submission. Works in Node.js and modern browsers.\n\n## Installation\n\n```bash\nnpm install @digital-card-twin/sdk\n# or\npnpm add @digital-card-twin/sdk\n```\n\n## Quick start\n\n```ts\nimport { DigitalCardTwinClient } from \"@digital-card-twin/sdk\";\n\nconst client = new DigitalCardTwinClient({\n  apiUrl: \"https://api.digital-card-twin.com\",\n  subgraphUrl: \"https://api.studio.thegraph.com/query/<ID>/digital-card-twin-registry/version/latest\",\n  rpcUrl: \"https://base-sepolia.g.alchemy.com/v2/<ALCHEMY_KEY>\",\n});\n```\n\n## API\n\n### `lookupCertificate(certNumber, company)`\n\nLook up a graded card by its certification number and grading company. Queries The Graph subgraph first, then falls back to direct on-chain RPC.\n\n```ts\nconst result = await client.lookupCertificate(\"85237194\", \"PSA\");\n\nif (result.found) {\n  console.log(result.tokenId);   // bigint\n  console.log(result.cardName);  // \"Charizard Holo 1st Edition\"\n  console.log(result.grade);     // \"PSA 10\"\n  console.log(result.owner);     // \"0x...\"\n  console.log(result.source);    // \"subgraph\" | \"rpc\"\n}\n```\n\nThe `company` parameter accepts either a plain name (`\"PSA\"`, `\"BGS\"`) or a pre-computed `bytes32` hex companyId (`\"0x...\"`).\n\n### `getTokenMetadata(tokenId)`\n\nFetch the ERC-721 metadata JSON for a minted token. Resolves `ipfs://` URIs via the configured gateway.\n\n```ts\nconst { metadata } = await client.getTokenMetadata(42n);\n\nconsole.log(metadata.name);        // \"PSA 10 — Charizard Holo\"\nconsole.log(metadata.image);       // IPFS or HTTP image URL\nconsole.log(metadata.attributes);  // [{ trait_type: \"Grade\", value: \"10\" }, ...]\n```\n\n### `submitCertificate(payload, apiKey)`\n\nSubmit a grading event to queue a new NFT mint. Requires a grading company API key.\n\n```ts\nconst result = await client.submitCertificate(\n  {\n    certificationNumber: \"85237194\",\n    companyId: \"PSA\",\n    cardName: \"Charizard Holo 1st Edition Base Set\",\n    grade: \"10\",\n    gradedAt: \"2024-01-15T10:00:00Z\",\n    // ... other fields\n  },\n  process.env.DCT_API_KEY\n);\n\nif (result.queued) {\n  console.log(\"Job ID:\", result.jobId);\n}\n\nif (result.alreadyMinted) {\n  console.log(\"Certificate already on-chain\");\n}\n```\n\n## Configuration\n\n| Option | Type | Default | Description |\n|---|---|---|---|\n| `apiUrl` | `string` | — | **Required.** Base URL of the digital-card-twin API |\n| `subgraphUrl` | `string` | — | The Graph subgraph query URL. Enables fast lookups without RPC |\n| `rpcUrl` | `string` | — | JSON-RPC endpoint (Base Sepolia or Base mainnet). Required for RPC fallback and `getTokenMetadata` |\n| `contractAddress` | `0x${string}` | Base Sepolia default | Override the registry contract address |\n| `ipfsGateway` | `string` | `https://cloudflare-ipfs.com` | Gateway used to resolve `ipfs://` URIs |\n| `requestTimeoutMs` | `number` | `10000` | Timeout per HTTP request in milliseconds |\n\n## Network\n\nThe SDK targets **Base Sepolia** (chain ID `84532`) by default. The deployed `DigitalCardTwinRegistry` contract address is `0xad3898d76af2024ee1ebd2f5ff10fdeefe64361b`.\n\n## Requirements\n\n- Node.js 18+ or a modern browser with native `fetch` and `BigInt` support\n- `viem` (peer dependency, installed automatically)\n","readmeFilename":"README.md"}