@aletheia-dev/plugin-sdk 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @aletheia-dev/plugin-sdk
 
+## 0.4.0
+
+### Minor Changes
+
+- [#10](https://github.com/akhiljames/aletheia/pull/10) [`82d5f0c`](https://github.com/akhiljames/aletheia/commit/82d5f0c54c499c633618008b5146ac3a1e7fd327) Thanks [@akhiljames](https://github.com/akhiljames)! - New subpath `@aletheia-dev/plugin-sdk/testing` with helpers for plugin authors' tests, with no
+  dependency on the platform: `createTestContext(manifest, options)` builds a `PluginContext` the
+  way the runtime does (config parsed through `configSchema`, declared secrets required) with a
+  recording logger (`entries`), a recording `fetch` stub (`calls`, 404 by default or a supplied
+  handler) and an in-memory document source (`MemoryDocuments`, `documentHandle`);
+  `conformance(plugin, { samples })` and `assertConformance` run the contract checks the runtime
+  applies (manifest, zod schemas, unknown action, outputs for sample inputs, `pending()` and the
+  `handleWebhook` round trip for asynchronous actions); `webhookRequest(plugin, { body, secret,
+headerName? })` builds the signed `WebhookRequest` the API would deliver. Additive: the root
+  export and the secret-reference convention are unchanged.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -202,37 +202,92 @@ implementation for tests, and the `Logger` type lets you accept any compatible l
 
 ## Testing locally
 
-A plugin is a plain object, so unit tests call `invoke` and `handleWebhook` directly with a
-hand-built context:
+`@aletheia-dev/plugin-sdk/testing` reproduces what the platform does around a plugin, so unit
+tests need no hand-built context or fakes. It has no dependency on the platform and works with
+any test runner.
 
 ```ts
-import { noopLogger, type PluginContext } from '@aletheia-dev/plugin-sdk';
-
-const ctx: PluginContext<{ threshold: number }> = {
-  tenantId: 'tenant-1',
-  config: { threshold: 0.8 },
-  secrets: { apiKey: 'test' },
-  logger: noopLogger,
-  fetch: async () => new Response(JSON.stringify({ hit: false, score: 0 })),
-  signal: new AbortController().signal,
-  callbackUrl: 'http://localhost:4000/webhooks/plugins/@acme/plugin-vendor',
-};
+import { WebhookRejectedError } from '@aletheia-dev/plugin-sdk';
+import {
+  assertConformance,
+  createTestContext,
+  documentHandle,
+  webhookRequest,
+} from '@aletheia-dev/plugin-sdk/testing';
+import plugin, { SIGNATURE_HEADER, manifest } from './index.js';
+
+const secrets = { apiKey: 'test', webhookSecret: 'wh' };
+
+// A context built like the runtime builds one: config parsed through configSchema (defaults
+// apply, bad config throws), declared secrets required, logger and fetch recording, documents
+// in memory. The default fetch answers 404; pass a handler to play the vendor.
+const ctx = createTestContext(manifest, {
+  config: { threshold: 0.9 },
+  secrets,
+  fetch: () => new Response(JSON.stringify({ matches: [] })),
+  documents: [documentHandle({ id: 'doc-1', text: '%PDF-1.4', contentType: 'application/pdf' })],
+});
+await plugin.invoke('screen', { name: 'Someone' }, ctx);
+ctx.fetch.calls[0]?.headers.authorization; // 'Bearer test'
+ctx.logger.entries; // [{ level, message, data, bindings }]
+
+// The request the API would hand handleWebhook, signed with signHmacSha256 into the header.
+const request = webhookRequest(plugin, {
+  body: { id: 'evt-1', externalId: 'ext-1', ok: true },
+  secret: 'wh',
+  headerName: SIGNATURE_HEADER,
+});
+await plugin.handleWebhook!(request, ctx);
+await expect(
+  plugin.handleWebhook!(
+    webhookRequest(plugin, { body: {}, secret: 'wrong', headerName: SIGNATURE_HEADER }),
+    ctx,
+  ),
+).rejects.toThrow(WebhookRejectedError);
+
+// The contract checks the runtime applies: manifest, schemas, unknown action, outputs for your
+// sample inputs, pending() and the webhook round trip for asynchronous actions.
+await assertConformance(plugin, {
+  context: { secrets },
+  samples: [
+    { action: 'screen', input: { name: 'Someone' } },
+    {
+      action: 'screenAsync',
+      input: { name: 'Someone' },
+      webhook: (externalId) =>
+        webhookRequest(plugin, {
+          body: { id: 'evt-2', externalId, ok: true },
+          secret: 'wh',
+          headerName: SIGNATURE_HEADER,
+        }),
+    },
+  ],
+});
 ```
 
+`conformance` returns the same result (`{ ok, checks, failures }`) without throwing. The
+[authoring guide](https://github.com/akhiljames/aletheia/blob/main/docs/integrate/plugins/authoring.md)
+builds a plugin and its tests step by step, and the
+[reference](https://github.com/akhiljames/aletheia/blob/main/docs/integrate/plugins/reference.md#testing-helpers-aletheia-devplugin-sdktesting)
+lists every option of the helpers.
+
 The repository's example plugins are the reference implementations:
 
+- [`examples/plugins/acme-screening`](https://github.com/akhiljames/aletheia/tree/main/examples/plugins/acme-screening)
+  is the authoring guide's plugin, built outside the monorepo against the published SDK;
 - [`plugins/mock-sanctions`](https://github.com/akhiljames/aletheia/tree/main/plugins/mock-sanctions)
-  — a synchronous action, an asynchronous twin and a signed webhook, with tests;
+  has a synchronous action, an asynchronous twin and a signed webhook, with tests;
 - [`plugins/doc-verify-mock`](https://github.com/akhiljames/aletheia/tree/main/plugins/doc-verify-mock)
-  — reads a document through `ctx.documents` and fires its own signed webhook;
+  reads a document through `ctx.documents` and fires its own signed webhook;
 - [`plugins/opensanctions`](https://github.com/akhiljames/aletheia/tree/main/plugins/opensanctions)
-  and [`plugins/sumsub`](https://github.com/akhiljames/aletheia/tree/main/plugins/sumsub) — real
+  and [`plugins/sumsub`](https://github.com/akhiljames/aletheia/tree/main/plugins/sumsub) are real
   vendors, including `webhookExternalId` for a dashboard-level webhook URL.
 
 To run a plugin against the platform, add it to the catalogue and configure it for a tenant:
-[`docs/plugins.md`](https://github.com/akhiljames/aletheia/blob/main/docs/plugins.md) covers the
-catalogue, tenant configuration, input mapping from workflows and rules, and what the platform
-does with each webhook outcome.
+[Vendor plugins](https://github.com/akhiljames/aletheia/blob/main/docs/integrate/plugins/vendors.md)
+covers the catalogue and tenant configuration, and the
+[reference](https://github.com/akhiljames/aletheia/blob/main/docs/integrate/plugins/reference.md)
+input mapping from workflows and rules and what the platform does with each webhook outcome.
 
 ## Versioning
 

package/dist/chunk-FEZWGVUS.js

@@ -0,0 +1,86 @@
+// src/index.ts
+import { z } from "zod";
+
+// src/logger.ts
+var noopLogger = {
+  debug: () => void 0,
+  info: () => void 0,
+  warn: () => void 0,
+  error: () => void 0,
+  child: () => noopLogger
+};
+
+// src/webhooks.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var WebhookRejectedError = class extends Error {
+  constructor(message = "webhook rejected") {
+    super(message);
+    this.name = "WebhookRejectedError";
+  }
+};
+function verifyHmacSha256(secret, rawBody, signature, encoding = "hex") {
+  const expected = createHmac("sha256", secret).update(rawBody).digest(encoding);
+  const a = Buffer.from(expected);
+  const b = Buffer.from(signature.trim());
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function signHmacSha256(secret, rawBody, encoding = "hex") {
+  return createHmac("sha256", secret).update(rawBody).digest(encoding);
+}
+
+// src/index.ts
+function pending(externalId) {
+  return { pending: true, externalId };
+}
+function isPending(value) {
+  return typeof value === "object" && value !== null && value.pending === true && typeof value.externalId === "string";
+}
+function definePlugin(plugin) {
+  return plugin;
+}
+function defineManifest(manifest) {
+  return manifest;
+}
+var isZodSchema = (value) => typeof value === "object" && value !== null && "_zod" in value;
+var ZodSchemaValue = z.custom(isZodSchema, { message: "expected a zod schema" });
+var PluginManifestSchema = z.object({
+  name: z.string().min(1).max(214).regex(
+    /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/,
+    "expected an npm package name"
+  ),
+  version: z.string().min(1),
+  description: z.string().optional(),
+  capabilities: z.array(z.string().min(1)),
+  configSchema: ZodSchemaValue,
+  secrets: z.array(z.string().min(1)),
+  actions: z.record(
+    z.string().min(1),
+    z.object({
+      description: z.string().optional(),
+      input: ZodSchemaValue,
+      output: ZodSchemaValue,
+      timeoutMs: z.number().int().positive().optional(),
+      retry: z.object({
+        maxAttempts: z.number().int().min(1).max(5),
+        backoffMs: z.number().int().nonnegative()
+      }).optional(),
+      idempotent: z.boolean().optional(),
+      async: z.object({
+        callbackTimeoutSeconds: z.number().int().min(1).max(7 * 24 * 3600)
+      }).optional()
+    })
+  )
+});
+
+export {
+  noopLogger,
+  WebhookRejectedError,
+  verifyHmacSha256,
+  signHmacSha256,
+  pending,
+  isPending,
+  definePlugin,
+  defineManifest,
+  PluginManifestSchema
+};
+//# sourceMappingURL=chunk-FEZWGVUS.js.map

package/dist/chunk-FEZWGVUS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/logger.ts","../src/webhooks.ts"],"sourcesContent":["import { z } from 'zod';\nimport type { Logger } from './logger.js';\nimport type { PluginDocuments } from './documents.js';\nimport type { WebhookEvent, WebhookRequest } from './webhooks.js';\n\nexport { noopLogger, type LogFn, type Logger } from './logger.js';\nexport type { DocumentHandle, PluginDocuments } from './documents.js';\nexport {\n  WebhookRejectedError,\n  signHmacSha256,\n  verifyHmacSha256,\n  type WebhookEvent,\n  type WebhookRequest,\n} from './webhooks.js';\n\n/** Retry hints for an action; applied by the runtime only when the call is safe to repeat. */\nexport interface PluginRetryPolicy {\n  /** Total attempts including the first (1 to 5). */\n  maxAttempts: number;\n  /** Base delay between attempts; multiplied by the attempt number. */\n  backoffMs: number;\n}\n\n/** One callable action a plugin exposes. Input and output are validated by the runtime. */\nexport interface PluginAction<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> {\n  description?: string;\n  input: I;\n  output: O;\n  /** Deadline for one attempt; the runtime aborts `ctx.signal` and fails the call when exceeded. */\n  timeoutMs?: number;\n  /** Retried by the runtime when `idempotent` is true or the caller supplies an idempotency key. */\n  retry?: PluginRetryPolicy;\n  /** Declares that repeating the action with the same input has no additional effect. */\n  idempotent?: boolean;\n  /**\n   * The action starts work at the vendor and completes later through a webhook. `invoke` must\n   * return `pending(externalId)`; the runtime waits for `handleWebhook` to report that id.\n   */\n  async?: { callbackTimeoutSeconds: number };\n}\n\n/** What an asynchronous action returns after starting work at the vendor. */\nexport interface PendingResult {\n  pending: true;\n  /** The vendor's identifier for the session, job or check; webhooks must carry it back. */\n  externalId: string;\n}\n\nexport function pending(externalId: string): PendingResult {\n  return { pending: true, externalId };\n}\n\nexport function isPending(value: unknown): value is PendingResult {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as { pending?: unknown }).pending === true &&\n    typeof (value as { externalId?: unknown }).externalId === 'string'\n  );\n}\n\nexport type PluginActions = Record<string, PluginAction>;\n\n/** Static description of a plugin package: what it needs (config, secrets) and what it offers. */\nexport interface PluginManifest<\n  C extends z.ZodType = z.ZodType,\n  A extends PluginActions = PluginActions,\n> {\n  /** npm package name, e.g. '@aletheia-dev/plugin-mock-sanctions'. */\n  name: string;\n  version: string;\n  description?: string;\n  /** Capability tags, e.g. ['sanctions.screen']. */\n  capabilities: string[];\n  /** Validates the tenant-provided, non-secret config. */\n  configSchema: C;\n  /** Names of secrets the plugin needs; resolved by the runtime per tenant. */\n  secrets: string[];\n  actions: A;\n}\n\n/** Per-tenant runtime context handed to every plugin call. */\nexport interface PluginContext<C = unknown> {\n  tenantId: string;\n  config: C;\n  secrets: Record<string, string>;\n  logger: Logger;\n  fetch: typeof fetch;\n  /** Aborted when the action's deadline passes; pass it to `fetch` so vendor calls stop too. */\n  signal: AbortSignal;\n  /** Stable key for the logical call (same across retries), when the caller provided one. */\n  idempotencyKey?: string;\n  /** Where the vendor must send webhooks for this plugin, when the deployment exposes one. */\n  callbackUrl?: string;\n  /**\n   * Read-only access to the tenant's clean documents (by document id). Present when the\n   * deployment has object storage; absent otherwise, so plugins must check before relying on it.\n   */\n  documents?: PluginDocuments;\n}\n\n/** Parsed config type of a manifest. */\nexport type PluginConfig<M extends PluginManifest> = z.output<M['configSchema']>;\n/** Union of a manifest's action names. */\nexport type ActionName<M extends PluginManifest> = keyof M['actions'] & string;\n/** Parsed input type of one action. */\nexport type ActionInput<M extends PluginManifest, K extends ActionName<M>> = z.output<\n  M['actions'][K]['input']\n>;\n/** Output type of one action. */\nexport type ActionOutput<M extends PluginManifest, K extends ActionName<M>> = z.output<\n  M['actions'][K]['output']\n>;\n\nexport interface Plugin<M extends PluginManifest = PluginManifest> {\n  manifest: M;\n  onInit?(ctx: PluginContext<PluginConfig<M>>): Promise<void> | void;\n  onShutdown?(): Promise<void> | void;\n  /**\n   * Dispatch one action. The runtime validates `input` against the action's input schema\n   * before calling and the return value against its output schema afterwards, so the\n   * signature stays loose here; use `ActionInput`/`ActionOutput` to type the body.\n   */\n  invoke(\n    action: ActionName<M>,\n    input: unknown,\n    ctx: PluginContext<PluginConfig<M>>,\n  ): Promise<unknown>;\n  /**\n   * Verifies and decodes a vendor webhook for one of this plugin's asynchronous actions.\n   * Return `null` to ignore the request, throw `WebhookRejectedError` for bad signatures.\n   */\n  handleWebhook?(\n    request: WebhookRequest,\n    ctx: PluginContext<PluginConfig<M>>,\n  ): Promise<WebhookEvent | null>;\n  /**\n   * Extracts the vendor's external id from a webhook whose URL carries no `?externalId=`\n   * (vendors with one dashboard-level webhook URL). Must be pure and need no secrets: it runs\n   * before the tenant is known, so it only decodes the body or headers. The platform resolves\n   * the tenant from the id and only then calls `handleWebhook` with the tenant context, which\n   * must still verify the signature. Return `null` when the request carries no id.\n   */\n  webhookExternalId?(request: WebhookRequest): string | null;\n}\n\n/** Identity helper so `manifest` drives inference for `onInit`/`invoke`. */\nexport function definePlugin<M extends PluginManifest>(plugin: Plugin<M>): Plugin<M> {\n  return plugin;\n}\n\n/** Identity helper that preserves the concrete schema and action types. */\nexport function defineManifest<C extends z.ZodType, A extends PluginActions>(\n  manifest: PluginManifest<C, A>,\n): PluginManifest<C, A> {\n  return manifest;\n}\n\nconst isZodSchema = (value: unknown): value is z.ZodType =>\n  typeof value === 'object' && value !== null && '_zod' in value;\n\nconst ZodSchemaValue = z.custom<z.ZodType>(isZodSchema, { message: 'expected a zod schema' });\n\n/** Runtime validation of a manifest's data parts (schemas are only checked to be zod schemas). */\nexport const PluginManifestSchema = z.object({\n  name: z\n    .string()\n    .min(1)\n    .max(214)\n    .regex(\n      /^(@[a-z0-9-~][a-z0-9-._~]*\\/)?[a-z0-9-~][a-z0-9-._~]*$/,\n      'expected an npm package name',\n    ),\n  version: z.string().min(1),\n  description: z.string().optional(),\n  capabilities: z.array(z.string().min(1)),\n  configSchema: ZodSchemaValue,\n  secrets: z.array(z.string().min(1)),\n  actions: z.record(\n    z.string().min(1),\n    z.object({\n      description: z.string().optional(),\n      input: ZodSchemaValue,\n      output: ZodSchemaValue,\n      timeoutMs: z.number().int().positive().optional(),\n      retry: z\n        .object({\n          maxAttempts: z.number().int().min(1).max(5),\n          backoffMs: z.number().int().nonnegative(),\n        })\n        .optional(),\n      idempotent: z.boolean().optional(),\n      async: z\n        .object({\n          callbackTimeoutSeconds: z\n            .number()\n            .int()\n            .min(1)\n            .max(7 * 24 * 3600),\n        })\n        .optional(),\n    }),\n  ),\n});\n","/**\n * Minimal structural logger contract handed to plugins (pino satisfies it).\n *\n * This is a deliberate copy of `@aletheia-dev/core`'s `logger.ts`: the SDK is published on its own\n * and must not pull the platform's core package in for three declarations. `logger.test.ts`\n * asserts the two stay assignable both ways, so the runtime can pass its core logger straight\n * into a plugin context.\n */\nexport type LogFn = (objOrMsg: object | string, msg?: string, ...args: unknown[]) => void;\n\nexport interface Logger {\n  debug: LogFn;\n  info: LogFn;\n  warn: LogFn;\n  error: LogFn;\n  child(bindings: Record<string, unknown>): Logger;\n}\n\nexport const noopLogger: Logger = {\n  debug: () => undefined,\n  info: () => undefined,\n  warn: () => undefined,\n  error: () => undefined,\n  child: () => noopLogger,\n};\n","import { createHmac, timingSafeEqual } from 'node:crypto';\n\n/** A vendor webhook as received by the API, with the raw body for signature verification. */\nexport interface WebhookRequest {\n  method: string;\n  /** Header names lower-cased. */\n  headers: Record<string, string>;\n  rawBody: Uint8Array;\n  query: Record<string, string>;\n}\n\n/** What a plugin extracted from a webhook. `null` from `handleWebhook` means \"ignore\". */\nexport interface WebhookEvent {\n  /** The vendor session id returned by the asynchronous action. */\n  externalId: string;\n  /** Vendor event id (or a stable hash) used for de-duplication. */\n  eventId: string;\n  status: 'completed' | 'failed' | 'pending';\n  /** Validated against the action's output schema when `status` is `completed`. */\n  output?: unknown;\n  error?: string;\n}\n\n/** Thrown by `handleWebhook` when the signature or payload is not acceptable (HTTP 401). */\nexport class WebhookRejectedError extends Error {\n  constructor(message = 'webhook rejected') {\n    super(message);\n    this.name = 'WebhookRejectedError';\n  }\n}\n\n/** Constant-time HMAC-SHA256 check of a raw body against a hex (or base64) signature. */\nexport function verifyHmacSha256(\n  secret: string,\n  rawBody: Uint8Array,\n  signature: string,\n  encoding: 'hex' | 'base64' = 'hex',\n): boolean {\n  const expected = createHmac('sha256', secret).update(rawBody).digest(encoding);\n  const a = Buffer.from(expected);\n  const b = Buffer.from(signature.trim());\n  return a.length === b.length && timingSafeEqual(a, b);\n}\n\nexport function signHmacSha256(\n  secret: string,\n  rawBody: Uint8Array,\n  encoding: 'hex' | 'base64' = 'hex',\n): string {\n  return createHmac('sha256', secret).update(rawBody).digest(encoding);\n}\n"],"mappings":";AAAA,SAAS,SAAS;;;ACkBX,IAAM,aAAqB;AAAA,EAChC,OAAO,MAAM;AAAA,EACb,MAAM,MAAM;AAAA,EACZ,MAAM,MAAM;AAAA,EACZ,OAAO,MAAM;AAAA,EACb,OAAO,MAAM;AACf;;;ACxBA,SAAS,YAAY,uBAAuB;AAwBrC,IAAM,uBAAN,cAAmC,MAAM;AAAA,EAC9C,YAAY,UAAU,oBAAoB;AACxC,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAGO,SAAS,iBACd,QACA,SACA,WACA,WAA6B,OACpB;AACT,QAAM,WAAW,WAAW,UAAU,MAAM,EAAE,OAAO,OAAO,EAAE,OAAO,QAAQ;AAC7E,QAAM,IAAI,OAAO,KAAK,QAAQ;AAC9B,QAAM,IAAI,OAAO,KAAK,UAAU,KAAK,CAAC;AACtC,SAAO,EAAE,WAAW,EAAE,UAAU,gBAAgB,GAAG,CAAC;AACtD;AAEO,SAAS,eACd,QACA,SACA,WAA6B,OACrB;AACR,SAAO,WAAW,UAAU,MAAM,EAAE,OAAO,OAAO,EAAE,OAAO,QAAQ;AACrE;;;AFFO,SAAS,QAAQ,YAAmC;AACzD,SAAO,EAAE,SAAS,MAAM,WAAW;AACrC;AAEO,SAAS,UAAU,OAAwC;AAChE,SACE,OAAO,UAAU,YACjB,UAAU,QACT,MAAgC,YAAY,QAC7C,OAAQ,MAAmC,eAAe;AAE9D;AAwFO,SAAS,aAAuC,QAA8B;AACnF,SAAO;AACT;AAGO,SAAS,eACd,UACsB;AACtB,SAAO;AACT;AAEA,IAAM,cAAc,CAAC,UACnB,OAAO,UAAU,YAAY,UAAU,QAAQ,UAAU;AAE3D,IAAM,iBAAiB,EAAE,OAAkB,aAAa,EAAE,SAAS,wBAAwB,CAAC;AAGrF,IAAM,uBAAuB,EAAE,OAAO;AAAA,EAC3C,MAAM,EACH,OAAO,EACP,IAAI,CAAC,EACL,IAAI,GAAG,EACP;AAAA,IACC;AAAA,IACA;AAAA,EACF;AAAA,EACF,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACzB,aAAa,EAAE,OAAO,EAAE,SAAS;AAAA,EACjC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AAAA,EACvC,cAAc;AAAA,EACd,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AAAA,EAClC,SAAS,EAAE;AAAA,IACT,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,IAChB,EAAE,OAAO;AAAA,MACP,aAAa,EAAE,OAAO,EAAE,SAAS;AAAA,MACjC,OAAO;AAAA,MACP,QAAQ;AAAA,MACR,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS;AAAA,MAChD,OAAO,EACJ,OAAO;AAAA,QACN,aAAa,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC;AAAA,QAC1C,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY;AAAA,MAC1C,CAAC,EACA,SAAS;AAAA,MACZ,YAAY,EAAE,QAAQ,EAAE,SAAS;AAAA,MACjC,OAAO,EACJ,OAAO;AAAA,QACN,wBAAwB,EACrB,OAAO,EACP,IAAI,EACJ,IAAI,CAAC,EACL,IAAI,IAAI,KAAK,IAAI;AAAA,MACtB,CAAC,EACA,SAAS;AAAA,IACd,CAAC;AAAA,EACH;AACF,CAAC;","names":[]}

package/dist/index.js

@@ -1,76 +1,14 @@
-// src/index.ts
-import { z } from "zod";
-
-// src/logger.ts
-var noopLogger = {
-  debug: () => void 0,
-  info: () => void 0,
-  warn: () => void 0,
-  error: () => void 0,
-  child: () => noopLogger
-};
-
-// src/webhooks.ts
-import { createHmac, timingSafeEqual } from "crypto";
-var WebhookRejectedError = class extends Error {
-  constructor(message = "webhook rejected") {
-    super(message);
-    this.name = "WebhookRejectedError";
-  }
-};
-function verifyHmacSha256(secret, rawBody, signature, encoding = "hex") {
-  const expected = createHmac("sha256", secret).update(rawBody).digest(encoding);
-  const a = Buffer.from(expected);
-  const b = Buffer.from(signature.trim());
-  return a.length === b.length && timingSafeEqual(a, b);
-}
-function signHmacSha256(secret, rawBody, encoding = "hex") {
-  return createHmac("sha256", secret).update(rawBody).digest(encoding);
-}
-
-// src/index.ts
-function pending(externalId) {
-  return { pending: true, externalId };
-}
-function isPending(value) {
-  return typeof value === "object" && value !== null && value.pending === true && typeof value.externalId === "string";
-}
-function definePlugin(plugin) {
-  return plugin;
-}
-function defineManifest(manifest) {
-  return manifest;
-}
-var isZodSchema = (value) => typeof value === "object" && value !== null && "_zod" in value;
-var ZodSchemaValue = z.custom(isZodSchema, { message: "expected a zod schema" });
-var PluginManifestSchema = z.object({
-  name: z.string().min(1).max(214).regex(
-    /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/,
-    "expected an npm package name"
-  ),
-  version: z.string().min(1),
-  description: z.string().optional(),
-  capabilities: z.array(z.string().min(1)),
-  configSchema: ZodSchemaValue,
-  secrets: z.array(z.string().min(1)),
-  actions: z.record(
-    z.string().min(1),
-    z.object({
-      description: z.string().optional(),
-      input: ZodSchemaValue,
-      output: ZodSchemaValue,
-      timeoutMs: z.number().int().positive().optional(),
-      retry: z.object({
-        maxAttempts: z.number().int().min(1).max(5),
-        backoffMs: z.number().int().nonnegative()
-      }).optional(),
-      idempotent: z.boolean().optional(),
-      async: z.object({
-        callbackTimeoutSeconds: z.number().int().min(1).max(7 * 24 * 3600)
-      }).optional()
-    })
-  )
-});
+import {
+  PluginManifestSchema,
+  WebhookRejectedError,
+  defineManifest,
+  definePlugin,
+  isPending,
+  noopLogger,
+  pending,
+  signHmacSha256,
+  verifyHmacSha256
+} from "./chunk-FEZWGVUS.js";
 export {
   PluginManifestSchema,
   WebhookRejectedError,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/logger.ts","../src/webhooks.ts"],"sourcesContent":["import { z } from 'zod';\nimport type { Logger } from './logger.js';\nimport type { PluginDocuments } from './documents.js';\nimport type { WebhookEvent, WebhookRequest } from './webhooks.js';\n\nexport { noopLogger, type LogFn, type Logger } from './logger.js';\nexport type { DocumentHandle, PluginDocuments } from './documents.js';\nexport {\n  WebhookRejectedError,\n  signHmacSha256,\n  verifyHmacSha256,\n  type WebhookEvent,\n  type WebhookRequest,\n} from './webhooks.js';\n\n/** Retry hints for an action; applied by the runtime only when the call is safe to repeat. */\nexport interface PluginRetryPolicy {\n  /** Total attempts including the first (1 to 5). */\n  maxAttempts: number;\n  /** Base delay between attempts; multiplied by the attempt number. */\n  backoffMs: number;\n}\n\n/** One callable action a plugin exposes. Input and output are validated by the runtime. */\nexport interface PluginAction<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> {\n  description?: string;\n  input: I;\n  output: O;\n  /** Deadline for one attempt; the runtime aborts `ctx.signal` and fails the call when exceeded. */\n  timeoutMs?: number;\n  /** Retried by the runtime when `idempotent` is true or the caller supplies an idempotency key. */\n  retry?: PluginRetryPolicy;\n  /** Declares that repeating the action with the same input has no additional effect. */\n  idempotent?: boolean;\n  /**\n   * The action starts work at the vendor and completes later through a webhook. `invoke` must\n   * return `pending(externalId)`; the runtime waits for `handleWebhook` to report that id.\n   */\n  async?: { callbackTimeoutSeconds: number };\n}\n\n/** What an asynchronous action returns after starting work at the vendor. */\nexport interface PendingResult {\n  pending: true;\n  /** The vendor's identifier for the session, job or check; webhooks must carry it back. */\n  externalId: string;\n}\n\nexport function pending(externalId: string): PendingResult {\n  return { pending: true, externalId };\n}\n\nexport function isPending(value: unknown): value is PendingResult {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as { pending?: unknown }).pending === true &&\n    typeof (value as { externalId?: unknown }).externalId === 'string'\n  );\n}\n\nexport type PluginActions = Record<string, PluginAction>;\n\n/** Static description of a plugin package: what it needs (config, secrets) and what it offers. */\nexport interface PluginManifest<\n  C extends z.ZodType = z.ZodType,\n  A extends PluginActions = PluginActions,\n> {\n  /** npm package name, e.g. '@aletheia-dev/plugin-mock-sanctions'. */\n  name: string;\n  version: string;\n  description?: string;\n  /** Capability tags, e.g. ['sanctions.screen']. */\n  capabilities: string[];\n  /** Validates the tenant-provided, non-secret config. */\n  configSchema: C;\n  /** Names of secrets the plugin needs; resolved by the runtime per tenant. */\n  secrets: string[];\n  actions: A;\n}\n\n/** Per-tenant runtime context handed to every plugin call. */\nexport interface PluginContext<C = unknown> {\n  tenantId: string;\n  config: C;\n  secrets: Record<string, string>;\n  logger: Logger;\n  fetch: typeof fetch;\n  /** Aborted when the action's deadline passes; pass it to `fetch` so vendor calls stop too. */\n  signal: AbortSignal;\n  /** Stable key for the logical call (same across retries), when the caller provided one. */\n  idempotencyKey?: string;\n  /** Where the vendor must send webhooks for this plugin, when the deployment exposes one. */\n  callbackUrl?: string;\n  /**\n   * Read-only access to the tenant's clean documents (by document id). Present when the\n   * deployment has object storage; absent otherwise, so plugins must check before relying on it.\n   */\n  documents?: PluginDocuments;\n}\n\n/** Parsed config type of a manifest. */\nexport type PluginConfig<M extends PluginManifest> = z.output<M['configSchema']>;\n/** Union of a manifest's action names. */\nexport type ActionName<M extends PluginManifest> = keyof M['actions'] & string;\n/** Parsed input type of one action. */\nexport type ActionInput<M extends PluginManifest, K extends ActionName<M>> = z.output<\n  M['actions'][K]['input']\n>;\n/** Output type of one action. */\nexport type ActionOutput<M extends PluginManifest, K extends ActionName<M>> = z.output<\n  M['actions'][K]['output']\n>;\n\nexport interface Plugin<M extends PluginManifest = PluginManifest> {\n  manifest: M;\n  onInit?(ctx: PluginContext<PluginConfig<M>>): Promise<void> | void;\n  onShutdown?(): Promise<void> | void;\n  /**\n   * Dispatch one action. The runtime validates `input` against the action's input schema\n   * before calling and the return value against its output schema afterwards, so the\n   * signature stays loose here; use `ActionInput`/`ActionOutput` to type the body.\n   */\n  invoke(\n    action: ActionName<M>,\n    input: unknown,\n    ctx: PluginContext<PluginConfig<M>>,\n  ): Promise<unknown>;\n  /**\n   * Verifies and decodes a vendor webhook for one of this plugin's asynchronous actions.\n   * Return `null` to ignore the request, throw `WebhookRejectedError` for bad signatures.\n   */\n  handleWebhook?(\n    request: WebhookRequest,\n    ctx: PluginContext<PluginConfig<M>>,\n  ): Promise<WebhookEvent | null>;\n  /**\n   * Extracts the vendor's external id from a webhook whose URL carries no `?externalId=`\n   * (vendors with one dashboard-level webhook URL). Must be pure and need no secrets: it runs\n   * before the tenant is known, so it only decodes the body or headers. The platform resolves\n   * the tenant from the id and only then calls `handleWebhook` with the tenant context, which\n   * must still verify the signature. Return `null` when the request carries no id.\n   */\n  webhookExternalId?(request: WebhookRequest): string | null;\n}\n\n/** Identity helper so `manifest` drives inference for `onInit`/`invoke`. */\nexport function definePlugin<M extends PluginManifest>(plugin: Plugin<M>): Plugin<M> {\n  return plugin;\n}\n\n/** Identity helper that preserves the concrete schema and action types. */\nexport function defineManifest<C extends z.ZodType, A extends PluginActions>(\n  manifest: PluginManifest<C, A>,\n): PluginManifest<C, A> {\n  return manifest;\n}\n\nconst isZodSchema = (value: unknown): value is z.ZodType =>\n  typeof value === 'object' && value !== null && '_zod' in value;\n\nconst ZodSchemaValue = z.custom<z.ZodType>(isZodSchema, { message: 'expected a zod schema' });\n\n/** Runtime validation of a manifest's data parts (schemas are only checked to be zod schemas). */\nexport const PluginManifestSchema = z.object({\n  name: z\n    .string()\n    .min(1)\n    .max(214)\n    .regex(\n      /^(@[a-z0-9-~][a-z0-9-._~]*\\/)?[a-z0-9-~][a-z0-9-._~]*$/,\n      'expected an npm package name',\n    ),\n  version: z.string().min(1),\n  description: z.string().optional(),\n  capabilities: z.array(z.string().min(1)),\n  configSchema: ZodSchemaValue,\n  secrets: z.array(z.string().min(1)),\n  actions: z.record(\n    z.string().min(1),\n    z.object({\n      description: z.string().optional(),\n      input: ZodSchemaValue,\n      output: ZodSchemaValue,\n      timeoutMs: z.number().int().positive().optional(),\n      retry: z\n        .object({\n          maxAttempts: z.number().int().min(1).max(5),\n          backoffMs: z.number().int().nonnegative(),\n        })\n        .optional(),\n      idempotent: z.boolean().optional(),\n      async: z\n        .object({\n          callbackTimeoutSeconds: z\n            .number()\n            .int()\n            .min(1)\n            .max(7 * 24 * 3600),\n        })\n        .optional(),\n    }),\n  ),\n});\n","/**\n * Minimal structural logger contract handed to plugins (pino satisfies it).\n *\n * This is a deliberate copy of `@aletheia-dev/core`'s `logger.ts`: the SDK is published on its own\n * and must not pull the platform's core package in for three declarations. `logger.test.ts`\n * asserts the two stay assignable both ways, so the runtime can pass its core logger straight\n * into a plugin context.\n */\nexport type LogFn = (objOrMsg: object | string, msg?: string, ...args: unknown[]) => void;\n\nexport interface Logger {\n  debug: LogFn;\n  info: LogFn;\n  warn: LogFn;\n  error: LogFn;\n  child(bindings: Record<string, unknown>): Logger;\n}\n\nexport const noopLogger: Logger = {\n  debug: () => undefined,\n  info: () => undefined,\n  warn: () => undefined,\n  error: () => undefined,\n  child: () => noopLogger,\n};\n","import { createHmac, timingSafeEqual } from 'node:crypto';\n\n/** A vendor webhook as received by the API, with the raw body for signature verification. */\nexport interface WebhookRequest {\n  method: string;\n  /** Header names lower-cased. */\n  headers: Record<string, string>;\n  rawBody: Uint8Array;\n  query: Record<string, string>;\n}\n\n/** What a plugin extracted from a webhook. `null` from `handleWebhook` means \"ignore\". */\nexport interface WebhookEvent {\n  /** The vendor session id returned by the asynchronous action. */\n  externalId: string;\n  /** Vendor event id (or a stable hash) used for de-duplication. */\n  eventId: string;\n  status: 'completed' | 'failed' | 'pending';\n  /** Validated against the action's output schema when `status` is `completed`. */\n  output?: unknown;\n  error?: string;\n}\n\n/** Thrown by `handleWebhook` when the signature or payload is not acceptable (HTTP 401). */\nexport class WebhookRejectedError extends Error {\n  constructor(message = 'webhook rejected') {\n    super(message);\n    this.name = 'WebhookRejectedError';\n  }\n}\n\n/** Constant-time HMAC-SHA256 check of a raw body against a hex (or base64) signature. */\nexport function verifyHmacSha256(\n  secret: string,\n  rawBody: Uint8Array,\n  signature: string,\n  encoding: 'hex' | 'base64' = 'hex',\n): boolean {\n  const expected = createHmac('sha256', secret).update(rawBody).digest(encoding);\n  const a = Buffer.from(expected);\n  const b = Buffer.from(signature.trim());\n  return a.length === b.length && timingSafeEqual(a, b);\n}\n\nexport function signHmacSha256(\n  secret: string,\n  rawBody: Uint8Array,\n  encoding: 'hex' | 'base64' = 'hex',\n): string {\n  return createHmac('sha256', secret).update(rawBody).digest(encoding);\n}\n"],"mappings":";AAAA,SAAS,SAAS;;;ACkBX,IAAM,aAAqB;AAAA,EAChC,OAAO,MAAM;AAAA,EACb,MAAM,MAAM;AAAA,EACZ,MAAM,MAAM;AAAA,EACZ,OAAO,MAAM;AAAA,EACb,OAAO,MAAM;AACf;;;ACxBA,SAAS,YAAY,uBAAuB;AAwBrC,IAAM,uBAAN,cAAmC,MAAM;AAAA,EAC9C,YAAY,UAAU,oBAAoB;AACxC,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAGO,SAAS,iBACd,QACA,SACA,WACA,WAA6B,OACpB;AACT,QAAM,WAAW,WAAW,UAAU,MAAM,EAAE,OAAO,OAAO,EAAE,OAAO,QAAQ;AAC7E,QAAM,IAAI,OAAO,KAAK,QAAQ;AAC9B,QAAM,IAAI,OAAO,KAAK,UAAU,KAAK,CAAC;AACtC,SAAO,EAAE,WAAW,EAAE,UAAU,gBAAgB,GAAG,CAAC;AACtD;AAEO,SAAS,eACd,QACA,SACA,WAA6B,OACrB;AACR,SAAO,WAAW,UAAU,MAAM,EAAE,OAAO,OAAO,EAAE,OAAO,QAAQ;AACrE;;;AFFO,SAAS,QAAQ,YAAmC;AACzD,SAAO,EAAE,SAAS,MAAM,WAAW;AACrC;AAEO,SAAS,UAAU,OAAwC;AAChE,SACE,OAAO,UAAU,YACjB,UAAU,QACT,MAAgC,YAAY,QAC7C,OAAQ,MAAmC,eAAe;AAE9D;AAwFO,SAAS,aAAuC,QAA8B;AACnF,SAAO;AACT;AAGO,SAAS,eACd,UACsB;AACtB,SAAO;AACT;AAEA,IAAM,cAAc,CAAC,UACnB,OAAO,UAAU,YAAY,UAAU,QAAQ,UAAU;AAE3D,IAAM,iBAAiB,EAAE,OAAkB,aAAa,EAAE,SAAS,wBAAwB,CAAC;AAGrF,IAAM,uBAAuB,EAAE,OAAO;AAAA,EAC3C,MAAM,EACH,OAAO,EACP,IAAI,CAAC,EACL,IAAI,GAAG,EACP;AAAA,IACC;AAAA,IACA;AAAA,EACF;AAAA,EACF,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACzB,aAAa,EAAE,OAAO,EAAE,SAAS;AAAA,EACjC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AAAA,EACvC,cAAc;AAAA,EACd,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AAAA,EAClC,SAAS,EAAE;AAAA,IACT,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,IAChB,EAAE,OAAO;AAAA,MACP,aAAa,EAAE,OAAO,EAAE,SAAS;AAAA,MACjC,OAAO;AAAA,MACP,QAAQ;AAAA,MACR,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS;AAAA,MAChD,OAAO,EACJ,OAAO;AAAA,QACN,aAAa,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC;AAAA,QAC1C,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY;AAAA,MAC1C,CAAC,EACA,SAAS;AAAA,MACZ,YAAY,EAAE,QAAQ,EAAE,SAAS;AAAA,MACjC,OAAO,EACJ,OAAO;AAAA,QACN,wBAAwB,EACrB,OAAO,EACP,IAAI,EACJ,IAAI,CAAC,EACL,IAAI,IAAI,KAAK,IAAI;AAAA,MACtB,CAAC,EACA,SAAS;AAAA,IACd,CAAC;AAAA,EACH;AACF,CAAC;","names":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}