@alvera-ai/platform-sdk 0.10.0-rc.16 → 0.10.0-rc.18

package/.agent/AGENTS.md

@@ -6,6 +6,54 @@ filesystem walk. Consumers include downstream agents writing
 code in CLIs, React apps, integration test suites, and code
 generators.
 
+> **Wiring this into your project:** run `npx @alvera-ai/platform-sdk
+> llm-export` from your project root to add a pointer to this corpus in
+> your `AGENTS.md` (and a `@AGENTS.md` import in `CLAUDE.md`). Idempotent.
+
+## ⚠ This file is a LOOKUP ONLY. Read the per-kind MD before emitting code.
+
+`AGENTS.md` (this file) is a **DIRECTORY**. It points you to
+per-kind MDs (`tools.md`, `workflows.md`, `data_sources.md`,
+etc.). It is **NOT** a schema reference, and you **CANNOT**
+ground any wire-level claim from this file alone.
+
+### Mandatory protocol before emitting any code that touches a kind
+
+1. **Locate the kind** in the Resources section below.
+2. **Open the kind's MD** (`<kind>.md`).
+3. **Read §1 (Wire shape) and §2 (Rules the type cannot encode)**
+   at minimum.
+4. **Every claim you emit** about wire shape, polymorphism,
+   constraints, enum values, or required fields **MUST be
+   grounded in §1 or §2 of the kind's MD**. If you cannot
+   point at the section, re-read before emitting.
+
+### Failure mode this prevents
+
+The one-line summaries in the Resources section are
+**navigation labels**, not schemas. Example:
+
+> The index line `workflows.md — Filter + decision + action;
+> standard + agent-driven variants` **cannot** tell you whether
+> `variant` is a body field. It is not. `workflows.md` §1 shows
+> the variant is **structural** — via the presence of the
+> `ai_agents[]` array on the request body — **not** a top-level
+> discriminator.
+
+An agent that paraphrases the index into a wire-level claim is
+**hallucinating**. The index summary is too compressed to encode
+polymorphism, constraints, enum values, or required fields.
+
+### Rule of thumb
+
+Treat index summaries like file names in a directory listing:
+useful for finding the right file, useless as a substitute for
+opening it. If you find yourself emitting a claim about a kind's
+wire shape without having opened that kind's MD in the current
+session, **stop and open it now**.
+
+---
+
 ## If you know MCP — vocabulary mapping
 
 The platform's resources don't implement MCP wire format, but
@@ -369,7 +417,7 @@ of restating:
 In your consumer repo, run:
 
 ```
-npx @alvera-ai/platform-sdk agent-init
+npx @alvera-ai/platform-sdk llm-export
 ```
 
 This writes a managed block into your `AGENTS.md` pointing back

package/.agent/cookbook/_setup/accounts_receivable.md

@@ -250,8 +250,8 @@ created tenant / datalake / user — each run mints fresh names via
 `runSuffix` so reruns do not collide, and the seeded local DB is
 cheap to reset (`mix ecto.reset` on the platform). When the
 validator graduates to continuous integration at Milestone 18
-(running against the offline Prism contract mock), no real state
-is created at all.
+(running against the mockoon-backed mock env at `ALVERA_ENV=mock`),
+no real state is created at all.
 
 # Outcome
 

package/.agent/cookbook/_setup/foundation.md

@@ -246,8 +246,8 @@ created tenant / datalake / user — each run mints fresh names via
 `runSuffix` so reruns do not collide, and the seeded local DB is
 cheap to reset (`mix ecto.reset` on the platform). When the
 validator graduates to continuous integration at Milestone 18
-(running against the offline Prism contract mock), no real state
-is created at all.
+(running against the mockoon-backed mock env at `ALVERA_ENV=mock`),
+no real state is created at all.
 
 # Outcome
 

package/.agent/cookbook/_setup/healthcare.md

@@ -247,8 +247,8 @@ created tenant / datalake / user — each run mints fresh names via
 `runSuffix` so reruns do not collide, and the seeded local DB is
 cheap to reset (`mix ecto.reset` on the platform). When the
 validator graduates to continuous integration at Milestone 18
-(running against the offline Prism contract mock), no real state
-is created at all.
+(running against the mockoon-backed mock env at `ALVERA_ENV=mock`),
+no real state is created at all.
 
 # Outcome
 

package/.agent/cookbook/_setup/payment_risk.md

@@ -251,8 +251,8 @@ created tenant / datalake / user — each run mints fresh names via
 `runSuffix` so reruns do not collide, and the seeded local DB is
 cheap to reset (`mix ecto.reset` on the platform). When the
 validator graduates to continuous integration at Milestone 18
-(running against the offline Prism contract mock), no real state
-is created at all.
+(running against the mockoon-backed mock env at `ALVERA_ENV=mock`),
+no real state is created at all.
 
 # Outcome
 

package/README.md

@@ -0,0 +1,40 @@
+# `@alvera-ai/platform-sdk`
+
+Typed SDK for the Alvera platform API — manage datalakes, data sources,
+tools, AI agents, action status updaters, and more.
+
+## Install
+
+```sh
+npm install @alvera-ai/platform-sdk
+# or: pnpm add / bun add / yarn add
+```
+
+## Usage
+
+```ts
+import { AlveraClient } from '@alvera-ai/platform-sdk'
+
+const alvera = new AlveraClient({ baseUrl, sessionToken })
+const { data } = await alvera.datalakes.list(tenantSlug)
+```
+
+## Agent setup
+
+This package ships an agent-docs corpus under `.agent/` (it lands at
+`node_modules/@alvera-ai/platform-sdk/.agent/` after install). Coding
+agents that walk `node_modules` discover it automatically.
+
+To wire a pointer into your project's `AGENTS.md` (and a `@AGENTS.md`
+import into `CLAUDE.md`), run — no global install needed:
+
+```sh
+npx @alvera-ai/platform-sdk llm-export
+```
+
+It writes an idempotent managed block; re-running replaces only that
+block. Start from the corpus index: `.agent/AGENTS.md`.
+
+## License
+
+Elastic-2.0

package/dist/bin/platform-sdk.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/bin/platform-sdk.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+//#region src/llm-export.ts
+const MARKER_BEGIN = "<!-- @alvera-ai/platform-sdk:BEGIN -->";
+const MARKER_END = "<!-- @alvera-ai/platform-sdk:END -->";
+const CLAUDE_IMPORT_LINE = "@AGENTS.md";
+const SDK_PACKAGE_NAME = "@alvera-ai/platform-sdk";
+function buildManagedBlock() {
+	const corpus = `node_modules/${SDK_PACKAGE_NAME}/.agent`;
+	return [
+		MARKER_BEGIN,
+		"",
+		"<!-- Managed by `alvera llm-export` — do not edit by hand. -->",
+		"<!-- Re-running the command replaces only this block. -->",
+		"",
+		`## \`${SDK_PACKAGE_NAME}\` corpus`,
+		"",
+		"The SDK ships an agent-docs corpus next to its npm install. Read the",
+		"corpus index first (Claude Code inlines this import):",
+		"",
+		`@${corpus}/AGENTS.md`,
+		"",
+		`Cookbook recipes live under \`${corpus}/cookbook/\`.`,
+		"",
+		"### Top-3 consumer gotchas",
+		"",
+		"1. **Updates use PUT, not PATCH.** The SDK exposes no PATCH method;",
+		`   mutations replace the resource whole. See \`${corpus}/mutations.md\`.`,
+		"2. **Paginated catalogs return `{ data, meta }`.** Catalog endpoints",
+		"   (`tools.list`, `dataSources.list`, etc.) wrap rows in `data` with a",
+		"   `meta` envelope — destructure, do not iterate the response directly.",
+		"3. **Resources are datalake-slug-scoped.** Every nested URL takes both",
+		"   `tenantSlug` and `datalakeSlug` — never a single slug. The datalake",
+		"   slug comes from the server (`api.datalakes.create`'s response).",
+		"",
+		MARKER_END
+	].join("\n");
+}
+function upsertManagedBlock(target, block) {
+	const beginIdx = target.indexOf(MARKER_BEGIN);
+	const endIdx = target.indexOf(MARKER_END);
+	if (beginIdx === -1 && endIdx === -1) return target + (target.length === 0 ? "" : target.endsWith("\n\n") ? "" : target.endsWith("\n") ? "\n" : "\n\n") + block + "\n";
+	if (beginIdx === -1 || endIdx === -1 || endIdx < beginIdx) throw new Error(`AGENTS.md: managed-block markers are damaged (BEGIN at ${beginIdx}, END at ${endIdx}). Fix by hand or remove both markers, then re-run llm-export.`);
+	const before = target.slice(0, beginIdx);
+	const after = target.slice(endIdx + 36);
+	return before + block + after;
+}
+function upsertClaudeImport(target) {
+	if (target.split("\n").some((line) => line.trim() === CLAUDE_IMPORT_LINE)) return {
+		next: target,
+		written: false
+	};
+	return {
+		next: target + (target.length === 0 ? "" : target.endsWith("\n\n") ? "" : target.endsWith("\n") ? "\n" : "\n\n") + CLAUDE_IMPORT_LINE + "\n",
+		written: true
+	};
+}
+function readOrEmpty(path) {
+	return existsSync(path) ? readFileSync(path, "utf8") : "";
+}
+function runLlmExport(cwd = process.cwd()) {
+	const block = buildManagedBlock();
+	const agentsMdPath = join(cwd, "AGENTS.md");
+	writeFileSync(agentsMdPath, upsertManagedBlock(readOrEmpty(agentsMdPath), block), "utf8");
+	const claudeMdPath = join(cwd, "CLAUDE.md");
+	const { next: claudeAfter, written: claudeImportWritten } = upsertClaudeImport(readOrEmpty(claudeMdPath));
+	writeFileSync(claudeMdPath, claudeAfter, "utf8");
+	return {
+		agentsMdPath,
+		claudeMdPath,
+		managedBlockBytes: block.length,
+		claudeImportWritten
+	};
+}
+
+//#endregion
+//#region src/bin/platform-sdk.ts
+function usage() {
+	process.stderr.write("Usage: npx @alvera-ai/platform-sdk <command>\n\nCommands:\n  llm-export    Write a managed AGENTS.md block pointing at the\n                SDK agent-docs corpus in node_modules; ensure\n                CLAUDE.md imports AGENTS.md. Idempotent.\n");
+}
+function main() {
+	const command = process.argv[2];
+	if (command === void 0 || command === "--help" || command === "-h") {
+		usage();
+		process.exit(command === void 0 ? 1 : 0);
+	}
+	if (command === "llm-export") try {
+		const result = runLlmExport(process.cwd());
+		process.stderr.write(`✓ ${result.agentsMdPath} (${result.managedBlockBytes} bytes in managed block)\n`);
+		process.stderr.write(`✓ ${result.claudeMdPath}${result.claudeImportWritten ? " (added @AGENTS.md import)" : " (@AGENTS.md import already present)"}\n`);
+		return;
+	} catch (err) {
+		process.stderr.write(`llm-export failed: ${err instanceof Error ? err.message : String(err)}\n`);
+		process.exit(1);
+	}
+	process.stderr.write(`unknown command "${command}".\n\n`);
+	usage();
+	process.exit(1);
+}
+main();
+
+//#endregion
+export {  };
+//# sourceMappingURL=platform-sdk.mjs.map

package/dist/bin/platform-sdk.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-sdk.mjs","names":[],"sources":["../../src/llm-export.ts","../../src/bin/platform-sdk.ts"],"sourcesContent":["// Consumer-facing agent-docs injector — the SDK-bin home of\n// `llm-export`. Writes a managed block into <cwd>/AGENTS.md that POINTS\n// at this package's shipped `.agent/` corpus (predictable npm path), and\n// ensures <cwd>/CLAUDE.md imports AGENTS.md.\n//\n// This writer is DUPLICATED in the CLI (packages/cli/src/cli/llm-export.ts)\n// for the brew `alvera llm-export` path. The two copies must emit a\n// byte-identical block — `buildManagedBlock()` below is kept verbatim in\n// both, and each package snapshot-tests its own output (architecture-\n// decisions §2.10.13). They are not shared via import: the CLI's tsconfig\n// rootDir forbids importing SDK source, a public SDK export was rejected\n// to keep the surface lean (CLAUDE.md #6), and the sharing would be\n// throwaway under a future Go CLI anyway.\n//\n// Unlike the CLI copy, this one is a LIBRARY module: it throws on damaged\n// markers rather than calling process.exit — the bin entry catches and\n// exits.\nimport { existsSync, readFileSync, writeFileSync } from 'node:fs'\nimport { join } from 'node:path'\n\nconst MARKER_BEGIN = '<!-- @alvera-ai/platform-sdk:BEGIN -->'\nconst MARKER_END = '<!-- @alvera-ai/platform-sdk:END -->'\nconst CLAUDE_IMPORT_LINE = '@AGENTS.md'\nconst SDK_PACKAGE_NAME = '@alvera-ai/platform-sdk'\n\nexport interface LlmExportResult {\n  agentsMdPath: string\n  claudeMdPath: string\n  managedBlockBytes: number\n  claudeImportWritten: boolean\n}\n\n// Pure + deterministic. MUST stay byte-identical to the CLI copy's\n// buildManagedBlock (§2.10.13 drift guard).\nexport function buildManagedBlock(): string {\n  const corpus = `node_modules/${SDK_PACKAGE_NAME}/.agent`\n  const lines: string[] = [\n    MARKER_BEGIN,\n    '',\n    '<!-- Managed by `alvera llm-export` — do not edit by hand. -->',\n    '<!-- Re-running the command replaces only this block. -->',\n    '',\n    `## \\`${SDK_PACKAGE_NAME}\\` corpus`,\n    '',\n    'The SDK ships an agent-docs corpus next to its npm install. Read the',\n    'corpus index first (Claude Code inlines this import):',\n    '',\n    `@${corpus}/AGENTS.md`,\n    '',\n    `Cookbook recipes live under \\`${corpus}/cookbook/\\`.`,\n    '',\n    '### Top-3 consumer gotchas',\n    '',\n    '1. **Updates use PUT, not PATCH.** The SDK exposes no PATCH method;',\n    `   mutations replace the resource whole. See \\`${corpus}/mutations.md\\`.`,\n    '2. **Paginated catalogs return `{ data, meta }`.** Catalog endpoints',\n    '   (`tools.list`, `dataSources.list`, etc.) wrap rows in `data` with a',\n    '   `meta` envelope — destructure, do not iterate the response directly.',\n    '3. **Resources are datalake-slug-scoped.** Every nested URL takes both',\n    '   `tenantSlug` and `datalakeSlug` — never a single slug. The datalake',\n    \"   slug comes from the server (`api.datalakes.create`'s response).\",\n    '',\n    MARKER_END,\n  ]\n  return lines.join('\\n')\n}\n\nexport function upsertManagedBlock(target: string, block: string): string {\n  const beginIdx = target.indexOf(MARKER_BEGIN)\n  const endIdx = target.indexOf(MARKER_END)\n\n  if (beginIdx === -1 && endIdx === -1) {\n    const tail =\n      target.length === 0\n        ? ''\n        : target.endsWith('\\n\\n')\n          ? ''\n          : target.endsWith('\\n')\n            ? '\\n'\n            : '\\n\\n'\n    return target + tail + block + '\\n'\n  }\n\n  if (beginIdx === -1 || endIdx === -1 || endIdx < beginIdx) {\n    throw new Error(\n      `AGENTS.md: managed-block markers are damaged ` +\n        `(BEGIN at ${beginIdx}, END at ${endIdx}). ` +\n        `Fix by hand or remove both markers, then re-run llm-export.`,\n    )\n  }\n\n  const before = target.slice(0, beginIdx)\n  const after = target.slice(endIdx + MARKER_END.length)\n  return before + block + after\n}\n\nexport function upsertClaudeImport(target: string): { next: string; written: boolean } {\n  const already = target.split('\\n').some((line) => line.trim() === CLAUDE_IMPORT_LINE)\n  if (already) return { next: target, written: false }\n  const tail =\n    target.length === 0\n      ? ''\n      : target.endsWith('\\n\\n')\n        ? ''\n        : target.endsWith('\\n')\n          ? '\\n'\n          : '\\n\\n'\n  return { next: target + tail + CLAUDE_IMPORT_LINE + '\\n', written: true }\n}\n\nfunction readOrEmpty(path: string): string {\n  return existsSync(path) ? readFileSync(path, 'utf8') : ''\n}\n\nexport function runLlmExport(cwd: string = process.cwd()): LlmExportResult {\n  const block = buildManagedBlock()\n\n  const agentsMdPath = join(cwd, 'AGENTS.md')\n  writeFileSync(agentsMdPath, upsertManagedBlock(readOrEmpty(agentsMdPath), block), 'utf8')\n\n  const claudeMdPath = join(cwd, 'CLAUDE.md')\n  const { next: claudeAfter, written: claudeImportWritten } = upsertClaudeImport(\n    readOrEmpty(claudeMdPath),\n  )\n  writeFileSync(claudeMdPath, claudeAfter, 'utf8')\n\n  return {\n    agentsMdPath,\n    claudeMdPath,\n    managedBlockBytes: block.length,\n    claudeImportWritten,\n  }\n}\n","#!/usr/bin/env node\n// The SDK's single bin (Stripe multi-subcommand pattern). Today the only\n// subcommand is `llm-export`, the consumer-facing agent-docs injector —\n// so an npm-only consumer runs `npx @alvera-ai/platform-sdk llm-export`\n// with no brew CLI install (architecture-decisions §2.10.13). The bin is\n// the ONLY thing reversed from inv #21; the SDK stays sub-export-less and\n// declares no postinstall.\nimport { runLlmExport } from '../llm-export.js'\n\nfunction usage(): void {\n  process.stderr.write(\n    'Usage: npx @alvera-ai/platform-sdk <command>\\n\\n' +\n      'Commands:\\n' +\n      '  llm-export    Write a managed AGENTS.md block pointing at the\\n' +\n      '                SDK agent-docs corpus in node_modules; ensure\\n' +\n      '                CLAUDE.md imports AGENTS.md. Idempotent.\\n',\n  )\n}\n\nfunction main(): void {\n  const command = process.argv[2]\n\n  if (command === undefined || command === '--help' || command === '-h') {\n    usage()\n    process.exit(command === undefined ? 1 : 0)\n  }\n\n  if (command === 'llm-export') {\n    try {\n      const result = runLlmExport(process.cwd())\n      process.stderr.write(\n        `✓ ${result.agentsMdPath} (${result.managedBlockBytes} bytes in managed block)\\n`,\n      )\n      process.stderr.write(\n        `✓ ${result.claudeMdPath}` +\n          `${result.claudeImportWritten ? ' (added @AGENTS.md import)' : ' (@AGENTS.md import already present)'}\\n`,\n      )\n      return\n    } catch (err) {\n      process.stderr.write(`llm-export failed: ${err instanceof Error ? err.message : String(err)}\\n`)\n      process.exit(1)\n    }\n  }\n\n  process.stderr.write(`unknown command \"${command}\".\\n\\n`)\n  usage()\n  process.exit(1)\n}\n\nmain()\n"],"mappings":";;;;;AAoBA,MAAM,eAAe;AACrB,MAAM,aAAa;AACnB,MAAM,qBAAqB;AAC3B,MAAM,mBAAmB;AAWzB,SAAgB,oBAA4B;CAC1C,MAAM,SAAS,gBAAgB,iBAAiB;AA6BhD,QA5BwB;EACtB;EACA;EACA;EACA;EACA;EACA,QAAQ,iBAAiB;EACzB;EACA;EACA;EACA;EACA,IAAI,OAAO;EACX;EACA,iCAAiC,OAAO;EACxC;EACA;EACA;EACA;EACA,kDAAkD,OAAO;EACzD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD,CACY,KAAK,KAAK;;AAGzB,SAAgB,mBAAmB,QAAgB,OAAuB;CACxE,MAAM,WAAW,OAAO,QAAQ,aAAa;CAC7C,MAAM,SAAS,OAAO,QAAQ,WAAW;AAEzC,KAAI,aAAa,MAAM,WAAW,GAShC,QAAO,UAPL,OAAO,WAAW,IACd,KACA,OAAO,SAAS,OAAO,GACrB,KACA,OAAO,SAAS,KAAK,GACnB,OACA,UACa,QAAQ;AAGjC,KAAI,aAAa,MAAM,WAAW,MAAM,SAAS,SAC/C,OAAM,IAAI,MACR,0DACe,SAAS,WAAW,OAAO,gEAE3C;CAGH,MAAM,SAAS,OAAO,MAAM,GAAG,SAAS;CACxC,MAAM,QAAQ,OAAO,MAAM,SAAS,GAAkB;AACtD,QAAO,SAAS,QAAQ;;AAG1B,SAAgB,mBAAmB,QAAoD;AAErF,KADgB,OAAO,MAAM,KAAK,CAAC,MAAM,SAAS,KAAK,MAAM,KAAK,mBAAmB,CACxE,QAAO;EAAE,MAAM;EAAQ,SAAS;EAAO;AASpD,QAAO;EAAE,MAAM,UAPb,OAAO,WAAW,IACd,KACA,OAAO,SAAS,OAAO,GACrB,KACA,OAAO,SAAS,KAAK,GACnB,OACA,UACqB,qBAAqB;EAAM,SAAS;EAAM;;AAG3E,SAAS,YAAY,MAAsB;AACzC,QAAO,WAAW,KAAK,GAAG,aAAa,MAAM,OAAO,GAAG;;AAGzD,SAAgB,aAAa,MAAc,QAAQ,KAAK,EAAmB;CACzE,MAAM,QAAQ,mBAAmB;CAEjC,MAAM,eAAe,KAAK,KAAK,YAAY;AAC3C,eAAc,cAAc,mBAAmB,YAAY,aAAa,EAAE,MAAM,EAAE,OAAO;CAEzF,MAAM,eAAe,KAAK,KAAK,YAAY;CAC3C,MAAM,EAAE,MAAM,aAAa,SAAS,wBAAwB,mBAC1D,YAAY,aAAa,CAC1B;AACD,eAAc,cAAc,aAAa,OAAO;AAEhD,QAAO;EACL;EACA;EACA,mBAAmB,MAAM;EACzB;EACD;;;;;AC1HH,SAAS,QAAc;AACrB,SAAQ,OAAO,MACb,wPAKD;;AAGH,SAAS,OAAa;CACpB,MAAM,UAAU,QAAQ,KAAK;AAE7B,KAAI,YAAY,UAAa,YAAY,YAAY,YAAY,MAAM;AACrE,SAAO;AACP,UAAQ,KAAK,YAAY,SAAY,IAAI,EAAE;;AAG7C,KAAI,YAAY,aACd,KAAI;EACF,MAAM,SAAS,aAAa,QAAQ,KAAK,CAAC;AAC1C,UAAQ,OAAO,MACb,KAAK,OAAO,aAAa,IAAI,OAAO,kBAAkB,4BACvD;AACD,UAAQ,OAAO,MACb,KAAK,OAAO,eACP,OAAO,sBAAsB,+BAA+B,uCAAuC,IACzG;AACD;UACO,KAAK;AACZ,UAAQ,OAAO,MAAM,sBAAsB,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI,CAAC,IAAI;AAChG,UAAQ,KAAK,EAAE;;AAInB,SAAQ,OAAO,MAAM,oBAAoB,QAAQ,QAAQ;AACzD,QAAO;AACP,SAAQ,KAAK,EAAE;;AAGjB,MAAM"}