{"_id":"@apd-spec/sdk","_rev":"3-768e0f21e209ec2734dcb2f630348ac5","name":"@apd-spec/sdk","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@apd-spec/sdk","version":"0.1.0","keywords":["apd","agent-procedure-definition","procedure-definition","workflow-specification","agent-workflow","approval-workflow","provenance","sop","sdk","typescript","json-schema","workflow"],"license":"Apache-2.0","_id":"@apd-spec/sdk@0.1.0","maintainers":[{"name":"shawnc7208","email":"ShawnC7208@gmail.com"}],"homepage":"https://github.com/ShawnC7208/APD#readme","bugs":{"url":"https://github.com/ShawnC7208/APD/issues"},"dist":{"shasum":"dd65bacbb14eb90f1abefb704524413fee666319","tarball":"https://registry.npmjs.org/@apd-spec/sdk/-/sdk-0.1.0.tgz","fileCount":8,"integrity":"sha512-X6+nEOoXkKLJn2KX28iy/Zy/QRYGzTrCdF5CTwSmq4FauKTvhQFNLgVmMvj2oIRQ3ryKRBppaEoqTXt6r3aavw==","signatures":[{"sig":"MEUCICZ5zTSJo81eyfL9iU4UcBFCb3NaCqacJDEwKYig5OdgAiEAjNgdjJKU5//1ktXMMvP2JwQ+Wx+z6zXFBwBT5A3Fdro=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":125039},"main":"./index.js","types":"./index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./index.d.ts","default":"./index.js","require":"./index.js"}},"gitHead":"0349a7934a137432313f1c43ad0eb194a5a9a277","scripts":{"test":"node test/run-tests.js","prepack":"npm run sync-schema","pretest":"npm run sync-schema","sync-schema":"node scripts/sync-schema.js"},"_npmUser":{"name":"shawnc7208","email":"ShawnC7208@gmail.com"},"repository":{"url":"git+https://github.com/ShawnC7208/APD.git","type":"git","directory":"packages/sdk-typescript"},"_npmVersion":"10.8.2","description":"TypeScript-friendly SDK for APD procedure definitions, workflow specifications, agent workflows, SOP export, and AER comparison","directories":{},"_nodeVersion":"20.20.2","dependencies":{"ajv":"^8.17.1","ajv-formats":"^3.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1776475146878_0.29975831904761474","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@apd-spec/sdk","version":"0.2.0","keywords":["apd","agent-procedure-definition","procedure-definition","workflow-specification","agent-workflow","approval-workflow","provenance","sop","sdk","typescript","json-schema","workflow"],"license":"Apache-2.0","_id":"@apd-spec/sdk@0.2.0","maintainers":[{"name":"shawnc7208","email":"ShawnC7208@gmail.com"}],"homepage":"https://github.com/ShawnC7208/APD#readme","bugs":{"url":"https://github.com/ShawnC7208/APD/issues"},"dist":{"shasum":"801f6c67988c6c2cbb37a5843c7e153ad2bafc68","tarball":"https://registry.npmjs.org/@apd-spec/sdk/-/sdk-0.2.0.tgz","fileCount":13,"integrity":"sha512-utW5rRM9K820KnWV8cNt8eKyyKO2IQGyZUAKRSsM27jvaztdLgyo6nPfJvlnNRnFNUfo/FbpPm0T7kNh6ICxIg==","signatures":[{"sig":"MEUCIQCwWdkLIcd/n/XgYgC8DE/hINoE2BydKs2mkSiofx1ZvgIgF82JO/4mdNOjJ/Y+SzI5tr770Ib8GfTzt1NoJFDumKc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":181161},"main":"./index.js","types":"./index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./index.d.ts","default":"./index.js","require":"./index.js"},"./node":{"types":"./node.d.ts","default":"./node.js","require":"./node.js"},"./browser":{"types":"./browser.d.ts","import":"./browser.mjs","default":"./browser.mjs","require":"./browser.js"}},"gitHead":"b5f29d50d8757559e1616e3cbbe7e9f24e8a13ef","scripts":{"test":"node test/run-tests.js","prepack":"npm run sync-schema","pretest":"npm run sync-schema","sync-schema":"node scripts/sync-schema.js"},"_npmUser":{"name":"shawnc7208","email":"ShawnC7208@gmail.com"},"repository":{"url":"git+https://github.com/ShawnC7208/APD.git","type":"git","directory":"packages/sdk-typescript"},"_npmVersion":"10.8.2","description":"TypeScript-friendly SDK for APD procedure definitions, workflow specifications, agent workflows, SOP export, and AER comparison","directories":{},"_nodeVersion":"20.20.2","dependencies":{"ajv":"^8.17.1","ajv-formats":"^3.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.0_1777601817653_0.17582103995140397","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@apd-spec/sdk","version":"0.3.0","description":"TypeScript-friendly SDK for APD procedure definitions, workflow specifications, agent workflows, SOP export, and AER comparison","license":"Apache-2.0","main":"./index.js","types":"./index.d.ts","exports":{".":{"types":"./index.d.ts","require":"./index.js","default":"./index.js"},"./browser":{"types":"./browser.d.ts","import":"./browser.mjs","require":"./browser.js","default":"./browser.mjs"},"./node":{"types":"./node.d.ts","require":"./node.js","default":"./node.js"}},"publishConfig":{"access":"public"},"scripts":{"sync-schema":"node scripts/sync-schema.js","pretest":"npm run sync-schema","prepack":"npm run sync-schema","test":"node test/run-tests.js"},"keywords":["apd","agent-procedure-definition","procedure-definition","workflow-specification","agent-workflow","approval-workflow","provenance","sop","sdk","typescript","json-schema","workflow"],"repository":{"type":"git","url":"git+https://github.com/ShawnC7208/APD.git","directory":"packages/sdk-typescript"},"homepage":"https://github.com/ShawnC7208/APD#readme","bugs":{"url":"https://github.com/ShawnC7208/APD/issues"},"engines":{"node":">=20"},"dependencies":{"ajv":"^8.17.1","ajv-formats":"^3.0.1"},"_id":"@apd-spec/sdk@0.3.0","_nodeVersion":"14.15.5","_npmVersion":"6.14.11","dist":{"integrity":"sha512-c+S+46uMmQSIiySp+TCjLAcVS1RrRYxjiXr7rFZxrPhCVcO20QJJ9cii9qc2Z5HXMJjATFt/EG5ugW/ipU55vg==","shasum":"884906f1dc57c226b8747a09c5d029630fccee06","tarball":"https://registry.npmjs.org/@apd-spec/sdk/-/sdk-0.3.0.tgz","fileCount":15,"unpackedSize":201844,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDyeTtTGD5dZAVWKpjC+qgf8pu0LHKdL00/hTF6V+qUQQIgUEqjkNlJOy98j9C+snHV2SnUmwhOTkwkBlohQNidpjY="}]},"_npmUser":{"name":"shawnc7208","email":"ShawnC7208@gmail.com"},"directories":{},"maintainers":[{"name":"shawnc7208","email":"ShawnC7208@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.3.0_1777726445590_0.5130654984721823"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-18T01:19:06.814Z","modified":"2026-05-02T12:54:05.866Z","0.1.0":"2026-04-18T01:19:07.067Z","0.2.0":"2026-05-01T02:16:57.849Z","0.3.0":"2026-05-02T12:54:05.742Z"},"bugs":{"url":"https://github.com/ShawnC7208/APD/issues"},"license":"Apache-2.0","homepage":"https://github.com/ShawnC7208/APD#readme","keywords":["apd","agent-procedure-definition","procedure-definition","workflow-specification","agent-workflow","approval-workflow","provenance","sop","sdk","typescript","json-schema","workflow"],"repository":{"type":"git","url":"git+https://github.com/ShawnC7208/APD.git","directory":"packages/sdk-typescript"},"description":"TypeScript-friendly SDK for APD procedure definitions, workflow specifications, agent workflows, SOP export, and AER comparison","maintainers":[{"name":"shawnc7208","email":"ShawnC7208@gmail.com"}],"readme":"# `@apd-spec/sdk`\n\n`@apd-spec/sdk` is the TypeScript-friendly SDK for creating, validating, summarizing, visualizing, and exporting APD procedure definitions and AER receipts.\n\n## Install from npm\n\n```bash\nnpm install @apd-spec/sdk\n```\n\nThen import it in your project:\n\n```js\nconst { APD, createApdScaffold, validateApd, validateAer, compareAerToApd, toSopMarkdown } = require(\"@apd-spec/sdk\");\n```\n\n## Entry points\n\nUse the entry point that matches your environment:\n\n- `@apd-spec/sdk` or `@apd-spec/sdk/node` for Node.js validation, schema loading, CLI helpers, and the full SDK surface\n- `@apd-spec/sdk/browser` for browser-safe APD parsing, APD types, and SOP markdown export without filesystem or schema-loading dependencies\n\nExample browser-safe import:\n\n```ts\nimport type { APDDocument } from \"@apd-spec/sdk/browser\";\nimport { toSopMarkdown } from \"@apd-spec/sdk/browser\";\n```\n\nIf you are working from a local clone of this repo, run:\n\n```bash\nnpm install\nnpm run build\n```\n\n## Primary exports\n\nBuilder:\n\n- `APD`\n- `createApdScaffold`\n- `createApdGenerationPrompt`\n- `generateApdDraftFromText`\n- `normalizeGeneratedApdDraft`\n\nRead and validate:\n\n- `parseApd`\n- `parseAer`\n- `validateApd`\n- `validateAer`\n- `summarizeApd`\n- `summarizeAer`\n- `compareAerToApd`\n\nRender and export:\n\n- `toMermaid`\n- `toSvg`\n- `toSopMarkdown`\n\nSchema and diagnostics helpers:\n\n- `loadSchema`\n- `loadApdSchema`\n- `loadAerSchema`\n- `graphDiagnostics`\n- `provenanceDiagnostics`\n- `bestPracticeDiagnostics`\n- `AERRecorder`\n\nNode-only integrity helpers from `@apd-spec/sdk/node`:\n\n- `canonicalizeJson`\n- `computeAerChainHash`\n- `sealAer`\n- `verifyAerIntegrity`\n\n## Start a new APD scaffold\n\n```js\nconst fs = require(\"fs\");\nconst { createApdScaffold } = require(\"@apd-spec/sdk\");\n\nconst scaffold = createApdScaffold({\n  title: \"Refund Review\",\n  procedureId: \"refund-review\"\n});\n\nfs.writeFileSync(\"refund-review.apd.json\", JSON.stringify(scaffold, null, 2) + \"\\n\");\n```\n\n## Normalize a generated APD draft\n\nProvider calls belong in your application or the CLI, but the SDK can create the prompt contract and normalize a provider draft into APD:\n\n```js\nconst { createApdGenerationPrompt, normalizeGeneratedApdDraft, validateApd } = require(\"@apd-spec/sdk\");\n\nconst prompt = createApdGenerationPrompt(\"Review a refund request, approve high-value refunds, then notify the customer.\");\nconst draft = await callYourModel(prompt);\nconst apd = normalizeGeneratedApdDraft(draft, {\n  producer: \"my-tool generate:openai\",\n  sourceText: prompt.input\n});\n\nconsole.log(validateApd(apd, { strict: true }));\n```\n\n## Builder example\n\n```js\nconst fs = require(\"fs\");\nconst { APD, toSopMarkdown } = require(\"@apd-spec/sdk\");\n\nconst apd = APD.create({\n  procedureId: \"hello-world\",\n  title: \"Hello World\",\n  summary: \"Minimal APD created with the SDK.\",\n  entryConditions: [\"A simple example is needed.\"]\n});\n\napd\n  .addAction({\n    id: \"step_1\",\n    name: \"Do the thing\",\n    instruction: \"Perform the step.\",\n    recovery: {\n      strategy: \"ask-user\",\n      instructions: \"Pause for review if the step cannot be completed confidently.\"\n    }\n  })\n  .addTerminal({\n    id: \"done\",\n    name: \"Finished\",\n    outcome: \"success\"\n  })\n  .connect(\"step_1\", \"done\");\n\nfs.writeFileSync(\"hello-world.apd.json\", apd.toString());\nconsole.log(apd.validate());\nconsole.log(toSopMarkdown(apd.toJSON()));\n```\n\n## Validate an existing APD\n\nReplace the example filename below with any APD file you have locally:\n\n```js\nconst fs = require(\"fs\");\nconst { parseApd, validateApd, summarizeApd } = require(\"@apd-spec/sdk\");\n\nconst document = parseApd(fs.readFileSync(\"refund-review.apd.json\", \"utf8\"));\nconst result = validateApd(document, { strict: true });\n\nconsole.log(result.valid);\nconsole.log(result.diagnostics);\nconsole.log(summarizeApd(document));\n```\n\n## Export an APD to SOP markdown\n\nReplace the example filename below with any APD file you have locally:\n\n```js\nconst fs = require(\"fs\");\nconst { parseApd, toSopMarkdown } = require(\"@apd-spec/sdk\");\n\nconst document = parseApd(fs.readFileSync(\"refund-review.apd.json\", \"utf8\"));\nconst sop = toSopMarkdown(document);\n\nfs.writeFileSync(\"/tmp/refund-review.sop.md\", sop);\n```\n\n`toSopMarkdown` preserves APD provenance markers as HTML comments so the runtime markdown stays readable while still retaining round-trip debugging hints.\n\n## Validate and compare AER\n\nReplace the example filenames below with your local APD and AER paths:\n\n```js\nconst fs = require(\"fs\");\nconst { validateAer, compareAerToApd } = require(\"@apd-spec/sdk\");\n\nconst apd = fs.readFileSync(\"refund-review.apd.json\", \"utf8\");\nconst aer = fs.readFileSync(\"refund-review.aer-v0.3.json\", \"utf8\");\n\nconsole.log(validateAer(aer, { strict: true }));\nconsole.log(compareAerToApd(apd, aer));\n```\n\nAER v0.1 remains supported for validation and summaries. AER v0.2 remains supported for comparison. AER v0.3 is the preferred signed receipt for compliance-grade integrity checks.\n\n## Seal and verify AER integrity\n\n```js\nconst fs = require(\"fs\");\nconst { sealAer, verifyAerIntegrity } = require(\"@apd-spec/sdk/node\");\n\nconst aer = JSON.parse(fs.readFileSync(\"refund-review.aer-v0.3.json\", \"utf8\"));\nconst privateKey = fs.readFileSync(\"adapter.pkcs8.b64\", \"utf8\");\nconst publicKey = fs.readFileSync(\"adapter.spki.b64\", \"utf8\");\n\nconst sealed = sealAer(aer, { privateKey, publicKey, attestExecutor: true });\nconsole.log(verifyAerIntegrity(sealed, { trustedPublicKeys: [publicKey] }));\n```\n\n`verifyAerIntegrity` requires trusted public keys supplied by the caller to report signatures and recorder attestations as valid. Embedded AER public keys are treated as claimed signer metadata, not as a trust root.\n\n## Related docs\n\n- [`../../docs/getting-started.md`](../../docs/getting-started.md)\n- [`../../docs/apd-for-agents.md`](../../docs/apd-for-agents.md)\n- [`../../docs/apd-to-sop-example.md`](../../docs/apd-to-sop-example.md)\n- [`../../adapters/sop-md-mapping.md`](../../adapters/sop-md-mapping.md)\n- [`../../spec/apd-v0.1.md`](../../spec/apd-v0.1.md)\n- [`../cli/README.md`](../cli/README.md)\n","readmeFilename":"README.md"}