@hyperscale0/adl 1.0.0-alpha.2 → 1.0.0-beta.10

package/examples/meridian-bank/README.md

@@ -1,65 +0,0 @@
-# Meridian Bank
-
-A complete, certified ADL adapter for a bank that does not exist. Every endpoint,
-status token, charge narrative, and account number here is invented, and the
-domain `meridian-bank.example` is reserved by RFC 2606 so nothing in this
-directory can point at a real institution.
-
-It exists for two reasons: it is the thing to copy when you write your own,
-and it is the proof that a third party can pass conformance with nothing but
-the published package.
-
-## What is here
-
-| File              | What it is                                                                                  |
-| ----------------- | ------------------------------------------------------------------------------------------- |
-| `index.ts`        | The adapter: vocabulary, profile, config, two capabilities. Read it top to bottom.          |
-| `fixtures/*.json` | Meridian's own bytes: two command responses, two status enquiries, a statement, a callback. |
-| `example.spec.ts` | Conformance, plus the checks that keep the declaration honest against the fixtures.         |
-
-## Meridian, briefly
-
-An imaginary European bank with a REST API:
-
-- **Errors ride the HTTP status.** A rejected payment is a 4xx with prose in
-  the body, which is `envelope: "http_status_error_body"`. A bank that answered
-  200 with a rejection token in the body would be `http_200_body_status`
-  instead, and the class is declared per operation because real providers are
-  inconsistent across their own endpoints.
-- **A payment is re-read by the reference Meridian minted**, so
-  `statusEnquiry.keys` is `provider_reference` and the path template carries
-  `{providerReference}`. That is the read-after-write: a submit whose response
-  we never saw is re-read, never resubmitted.
-- **Incoming credits are learned from statements**, so the `bank_credit`
-  capability declares `egress: "none"` and records what observation saw.
-- **Fees and tax post separately** as `MERIDIAN FEE ...` and `MERIDIAN TAX ...`
-  debits, which is why both narrative prefixes are declared: unrecognized, they
-  would land as unexplained statement lines.
-- **The statement echoes our reference**, so `statementDebitReference` is
-  `customer_reference`. Reading Meridian's own entry id instead would make
-  every payout we instructed look like an unexplained debit.
-
-## Run it
-
-From the package root:
-
-```bash
-bun run conformance -- ./examples/meridian-bank
-bun test examples/meridian-bank
-```
-
-## Copying it
-
-1. Copy the directory and rename `meridian` throughout. The provider key is
-   lowercase and machine-shaped (`^[a-z][a-z0-9_.-]{0,79}$`).
-2. Replace the vocabulary with the operations and resources your product
-   actually uses.
-3. Replace every profile fact with what your bank does. Do not carry a
-   Meridian value across because it looked plausible: a fact you have not
-   established is declared absent, and conformance will tell you which ones
-   are still open.
-4. Replace the fixtures with real captures from your provider's sandbox, and
-   keep `example.spec.ts` pointed at them. A declaration that certifies but
-   cannot read its own sandbox capture is not finished.
-
-`../../docs/authoring-guide.md` explains every field.

package/examples/meridian-bank/example.spec.ts

@@ -1,162 +0,0 @@
-/**
- * The example's own test, and the shape yours should take: conformance is
- * the gate, and the fixtures keep the declaration honest against the bytes
- * the bank actually sends. A declaration that certifies but cannot read its
- * own sandbox capture is not finished.
- */
-
-import { readFileSync } from "node:fs";
-
-import { partnerBankConformanceFindings } from "@hyperscale0/adl";
-import { describe, expect, test } from "bun:test";
-
-import { meridianAdapters, meridianProfile } from "./index.js";
-
-interface ExchangeFixture {
-  readonly kind: "command" | "enquiry";
-  readonly operation: string;
-  readonly response: {
-    readonly httpStatus: number;
-    readonly body: Record<string, unknown>;
-  };
-}
-
-interface StatementFixture {
-  readonly format: string;
-  readonly entries: readonly {
-    readonly amount: string;
-    readonly customerReference: string | null;
-    readonly narrative: string;
-  }[];
-}
-
-interface NotificationFixture {
-  readonly eventKind: string;
-  readonly payload: Record<string, unknown>;
-}
-
-function fixture<T>(name: string): T {
-  return JSON.parse(
-    readFileSync(new URL(`./fixtures/${name}.json`, import.meta.url), "utf8"),
-  ) as T;
-}
-
-const exchanges = [
-  fixture<ExchangeFixture>("payout-submit-accepted"),
-  fixture<ExchangeFixture>("payout-submit-declined"),
-  fixture<ExchangeFixture>("payout-status-settled"),
-  fixture<ExchangeFixture>("payout-status-replay"),
-];
-const statement = fixture<StatementFixture>("statement-camt053");
-const notification = fixture<NotificationFixture>("webhook-payout-settled");
-
-const [payoutAdapter] = meridianAdapters;
-if (!payoutAdapter) throw new Error("payout adapter missing");
-
-/** The same normalization a runtime uses to match a status token. */
-function normalize(token: string): string {
-  return token.trim().toUpperCase();
-}
-
-const canonicalStateFor = new Map(
-  Object.entries(meridianProfile.lifecycleVocabulary).map(
-    ([spelling, state]) => [normalize(spelling), state as string],
-  ),
-);
-
-describe("meridian bank adapter", () => {
-  test("every capability certifies with zero findings", () => {
-    for (const adapter of meridianAdapters) {
-      expect({
-        capability: adapter.capability,
-        findings: partnerBankConformanceFindings(adapter),
-      }).toEqual({ capability: adapter.capability, findings: [] });
-    }
-  });
-
-  test("the lifecycle vocabulary spells every token the bank sends", () => {
-    for (const exchange of exchanges) {
-      const token = exchange.response.body["status"];
-      expect(typeof token).toBe("string");
-      expect(canonicalStateFor.get(normalize(token as string))).toBeDefined();
-    }
-  });
-
-  test("the declared envelope class is how the fixtures actually read", () => {
-    // http_status_error_body: the HTTP status carries the outcome and a
-    // failure body is prose. Reading the body of a 2xx for a rejection, or
-    // treating a 4xx as a lost response, would strand the payment.
-    expect(payoutAdapter.operationMap["payout.submit"]?.envelope).toBe(
-      "http_status_error_body",
-    );
-    for (const exchange of exchanges) {
-      if (exchange.kind !== "command") continue;
-      const state = canonicalStateFor.get(
-        normalize(exchange.response.body["status"] as string),
-      );
-      if (state === "failed") {
-        expect(exchange.response.httpStatus).toBeGreaterThanOrEqual(400);
-        expect(typeof exchange.response.body["message"]).toBe("string");
-        continue;
-      }
-      expect(exchange.response.httpStatus).toBeLessThan(400);
-    }
-  });
-
-  test("the statement format is declared and has a fetch window", () => {
-    const formats: readonly string[] = meridianProfile.statementFormats;
-    expect(formats).toContain(statement.format);
-    const windows: Record<string, unknown> = meridianProfile.windows.statements;
-    expect(windows[statement.format]).toBeDefined();
-  });
-
-  test("the charge narratives recognize the bank's own debits", () => {
-    const startsWithAny = (narrative: string, prefixes: readonly string[]) =>
-      prefixes.some((prefix) => normalize(narrative).startsWith(prefix));
-
-    const { charge, vat } = meridianProfile.charges.narratives;
-    const chargeLines = statement.entries.filter((entry) =>
-      startsWithAny(entry.narrative, charge),
-    );
-    const vatLines = statement.entries.filter((entry) =>
-      startsWithAny(entry.narrative, vat),
-    );
-    expect(chargeLines).toHaveLength(1);
-    expect(vatLines).toHaveLength(1);
-  });
-
-  test("an instructed payout is attributable on the statement", () => {
-    // statementDebitReference says which reference comes back. Every debit
-    // that is not one of the bank's own charge lines must carry it, or the
-    // ledger cannot prove the debit was ours.
-    expect(meridianProfile.statementDebitReference).toBe("customer_reference");
-    const chargePrefixes = [
-      ...meridianProfile.charges.narratives.charge,
-      ...meridianProfile.charges.narratives.vat,
-    ];
-    const instructedDebits = statement.entries.filter(
-      (entry) =>
-        entry.amount.startsWith("-") &&
-        !chargePrefixes.some((prefix) =>
-          normalize(entry.narrative).startsWith(prefix),
-        ),
-    );
-    expect(instructedDebits).not.toHaveLength(0);
-    for (const debit of instructedDebits) {
-      expect(typeof debit.customerReference).toBe("string");
-    }
-  });
-
-  test("the webhook plan describes the callback the bank sends", () => {
-    const plan = Object.entries(payoutAdapter.webhookMap).find(
-      ([eventKind]) => eventKind === notification.eventKind,
-    )?.[1];
-    expect(plan).toBeDefined();
-    if (!plan) return;
-    for (const field of plan.requiredPayloadFields) {
-      expect(notification.payload[field]).toBeDefined();
-    }
-    expect(notification.payload[plan.resourceIdField]).toBeDefined();
-    expect(notification.payload[plan.timestampField]).toBeDefined();
-  });
-});

package/examples/meridian-bank/fixtures/payout-status-replay.json

@@ -1,19 +0,0 @@
-{
-  "kind": "enquiry",
-  "operation": "payout.submit",
-  "request": {
-    "method": "GET",
-    "path": "/v2/payments/MER-9F3K2"
-  },
-  "response": {
-    "httpStatus": 200,
-    "body": {
-      "providerReference": "MER-9F3K2",
-      "paymentReference": "HS-PAY-0007",
-      "status": "REPLAY_SETTLED",
-      "originalProviderReference": "MER-9F3K2",
-      "valueDate": "2026-03-03",
-      "settledAt": "2026-03-03T09:04:41Z"
-    }
-  }
-}

package/examples/meridian-bank/fixtures/payout-status-settled.json

@@ -1,19 +0,0 @@
-{
-  "kind": "enquiry",
-  "operation": "payout.submit",
-  "request": {
-    "method": "GET",
-    "path": "/v2/payments/MER-9F3K2"
-  },
-  "response": {
-    "httpStatus": 200,
-    "body": {
-      "providerReference": "MER-9F3K2",
-      "paymentReference": "HS-PAY-0007",
-      "status": "SETTLED",
-      "valueDate": "2026-03-03",
-      "settledAt": "2026-03-03T09:04:41Z",
-      "chargeAmount": "1.50"
-    }
-  }
-}

package/examples/meridian-bank/fixtures/payout-submit-accepted.json

@@ -1,26 +0,0 @@
-{
-  "kind": "command",
-  "operation": "payout.submit",
-  "request": {
-    "method": "POST",
-    "path": "/v2/payments",
-    "body": {
-      "instructionId": "HS-INS-0007",
-      "endToEndId": "HS-E2E-0007",
-      "paymentReference": "HS-PAY-0007",
-      "amount": "2500.00",
-      "currency": "EUR",
-      "creditorName": "Acme Ltd",
-      "creditorAccount": "IE29MERI93115212345678",
-      "requestedValueDate": "2026-03-03"
-    }
-  },
-  "response": {
-    "httpStatus": 202,
-    "body": {
-      "providerReference": "MER-9F3K2",
-      "status": "QUEUED",
-      "receivedAt": "2026-03-02T13:20:05Z"
-    }
-  }
-}

package/examples/meridian-bank/fixtures/payout-submit-declined.json

@@ -1,25 +0,0 @@
-{
-  "kind": "command",
-  "operation": "payout.submit",
-  "request": {
-    "method": "POST",
-    "path": "/v2/payments",
-    "body": {
-      "instructionId": "HS-INS-0008",
-      "endToEndId": "HS-E2E-0008",
-      "paymentReference": "HS-PAY-0008",
-      "amount": "40.00",
-      "currency": "EUR",
-      "creditorName": "Closed Account Ltd",
-      "creditorAccount": "IE29MERI93115299999999",
-      "requestedValueDate": "2026-03-03"
-    }
-  },
-  "response": {
-    "httpStatus": 422,
-    "body": {
-      "status": "DECLINED",
-      "message": "creditor account is closed"
-    }
-  }
-}

package/examples/meridian-bank/fixtures/statement-camt053.json

@@ -1,45 +0,0 @@
-{
-  "kind": "statement",
-  "format": "camt_053",
-  "account": "IE29MERI93115200000001",
-  "statementDate": "2026-03-03",
-  "entries": [
-    {
-      "entryReference": "MER-ENT-88213",
-      "customerReference": "HS-PAY-0007",
-      "amount": "-2500.00",
-      "currency": "EUR",
-      "narrative": "PAYMENT TO ACME LTD",
-      "bookingDate": "2026-03-03",
-      "valueDate": "2026-03-03"
-    },
-    {
-      "entryReference": "MER-ENT-88214",
-      "customerReference": null,
-      "amount": "-1.50",
-      "currency": "EUR",
-      "narrative": "MERIDIAN FEE HS-PAY-0007",
-      "bookingDate": "2026-03-03",
-      "valueDate": "2026-03-03"
-    },
-    {
-      "entryReference": "MER-ENT-88215",
-      "customerReference": null,
-      "amount": "-0.35",
-      "currency": "EUR",
-      "narrative": "MERIDIAN TAX HS-PAY-0007",
-      "bookingDate": "2026-03-03",
-      "valueDate": "2026-03-03"
-    },
-    {
-      "entryReference": "MER-ENT-88301",
-      "customerReference": null,
-      "amount": "1200.00",
-      "currency": "EUR",
-      "narrative": "INBOUND TRANSFER FROM BUYER 4471",
-      "financialAddressId": "fa_2299",
-      "bookingDate": "2026-03-03",
-      "valueDate": "2026-03-03"
-    }
-  ]
-}

package/examples/meridian-bank/fixtures/webhook-payout-settled.json

@@ -1,11 +0,0 @@
-{
-  "kind": "notification",
-  "eventKind": "payout.settled",
-  "payload": {
-    "payoutId": "pyt_01HQ8",
-    "providerReference": "MER-9F3K2",
-    "valueDate": "2026-03-03",
-    "chargeAmount": "1.50",
-    "completedAt": "2026-03-03T09:04:41Z"
-  }
-}

package/examples/meridian-bank/index.ts

@@ -1,262 +0,0 @@
-/**
- * Meridian Bank: a complete, certified adapter for a bank that does not
- * exist. Every endpoint, status token, and charge narrative below is
- * invented. It is here to be read top to bottom and copied.
- *
- * The order of the file is the order you write one:
- *
- *   1. the vocabulary -- the closed operation, resource, and webhook unions
- *      your product uses;
- *   2. the profile -- what the bank does, as facts;
- *   3. the config -- where the credentials live, never what they are;
- *   4. the adapters -- one per capability, validated at import.
- *
- * `docs/authoring-guide.md` explains every field. `fixtures/` holds the
- * bank's own bytes, and `example.spec.ts` proves the declaration matches
- * them.
- */
-
-import {
-  createProviderAdapterRegistry,
-  type PartnerBankAdapterProfile,
-  type ProviderAdapterVocabulary,
-  type ProviderConfig,
-} from "@hyperscale0/adl";
-
-/**
- * The slice of the platform vocabulary this bank serves, spelled as closed
- * literal unions. Nothing here comes from a private import: the operation and
- * resource names are the published ones.
- */
-export interface MeridianVocabulary extends ProviderAdapterVocabulary {
-  readonly capability: "payout_execution" | "bank_credit";
-  readonly domain: "payouts" | "deposits";
-  readonly meter: "external_payout";
-  readonly obligation:
-    | "payout_submission"
-    | "payout_execution"
-    | "payout_return"
-    | "bank_credit";
-  readonly operation:
-    | "payout.submit"
-    | "payout.complete"
-    | "payout.fail"
-    | "payout.return"
-    | "deposit.record";
-  readonly resource: "payout" | "deposit";
-  readonly webhookOperation: "payout.complete" | "deposit.record";
-  readonly webhookResource: "payout" | "deposit";
-  readonly webhookResourceId: "payoutId" | "depositId";
-}
-
-const defineMeridianAdapters =
-  createProviderAdapterRegistry<MeridianVocabulary>();
-
-/**
- * Meridian as its documentation and its sandbox describe it. Each fact is
- * something a runtime would otherwise have to guess, and a guess here is a
- * stranded payment.
- */
-export const meridianProfile = {
-  kind: "partner_bank",
-  wireCodec: "rest_json",
-  auth: {
-    // Machine-to-machine client credentials, plus a detached signature over
-    // the request body that Meridian verifies with the channel certificate.
-    envelope: "oauth2_client_credentials",
-    signing: "detached_signature",
-  },
-  idempotencySpine: {
-    // Meridian grades a replay on the instruction id we mint, and refuses a
-    // second payment carrying a payment reference it has already settled.
-    dedupeKeys: ["instructionId", "paymentReference"],
-    instructionId: { maxLength: 32 },
-    endToEndId: { maxLength: 32 },
-    paymentReference: { maxLength: 20 },
-  },
-  /**
-   * Meridian's own status tokens on the left, the canonical states on the
-   * right. Runtimes match after trimming and upper-casing, so a token that
-   * only differs by case or padding needs no second entry.
-   *
-   * Both replay verdicts are spelled: without them a crash-recovery
-   * resubmission reads as a fresh failure and the payout is instructed twice.
-   */
-  lifecycleVocabulary: {
-    QUEUED: "received",
-    IN_REVIEW: "received",
-    AUTHORISED: "accepted",
-    SETTLED: "processed",
-    DECLINED: "failed",
-    RECALLED: "returned",
-    REPLAY_SETTLED: "duplicate_original_succeeded",
-    REPLAY_DECLINED: "duplicate_original_rejected",
-  },
-  executedReadBack: {
-    fxRate: "final_status_only",
-    // Meridian never moves a payment to another rail behind our back.
-    railSubstitution: "none",
-  },
-  charges: {
-    // The bank raises its fee and its tax as two separate debits, each
-    // recognizable only by the wording it prints. Prefixes, because the
-    // trailing part names the payment being charged for.
-    narratives: {
-      charge: ["MERIDIAN FEE"],
-      vat: ["MERIDIAN TAX"],
-    },
-    posting: "post_hoc",
-    vat: "separate_line",
-  },
-  windows: {
-    paymentCutoff: {
-      time: "16:30",
-      // The bank's wall clock, not the platform's.
-      timeZone: "Europe/Dublin",
-      beforeCutoffValueDate: "D+0",
-      afterCutoffValueDate: "D+1",
-    },
-    valueDateMaxDaysAhead: 30,
-    statements: {
-      // End of day pages over history, so it declares how far back the
-      // archive goes and how many days one request may cover.
-      camt_053: {
-        availability: "T-1",
-        lookbackDays: 90,
-        statementDaysPerRequest: 7,
-      },
-      // Intraday is today or nothing, so it owes no paging facts.
-      camt_052: { availability: "today_only" },
-    },
-  },
-  // Meridian echoes the reference we sent, not its own entry id. Reading the
-  // entry id instead would leave every payout we instructed looking like an
-  // unexplained debit.
-  statementDebitReference: "customer_reference",
-  statementFormats: ["camt_053", "camt_052"],
-  // The callback is a hint that a poll is due. Polling is the fact.
-  notificationMechanisms: ["poll", "webhook"],
-  financialAddressProvisioning: {
-    mechanism: "api",
-    quota: "none",
-    pricing: "none",
-  },
-  limitFacts: {
-    access: "read_only",
-    dimensions: ["daily", "per_transaction"],
-  },
-} as const satisfies PartnerBankAdapterProfile;
-
-/**
- * A locator, never a value. The registry validator refuses a blank locator
- * and has no field a secret could be written into.
- */
-const meridianConfig = {
-  baseUrl: "https://api.meridian-bank.example/v2",
-  credentialRef: {
-    source: "environment",
-    name: "MERIDIAN_BANK_CREDENTIALS",
-  },
-} as const satisfies ProviderConfig;
-
-/**
- * One adapter per capability, both carrying the same bank profile. The
- * registry validates shape at import; `example.spec.ts` runs conformance.
- */
-export const meridianAdapters = defineMeridianAdapters([
-  {
-    provider: "meridian_bank",
-    capability: "payout_execution",
-    domain: "payouts",
-    egress: "rest",
-    operationMap: {
-      "payout.submit": {
-        // Read-after-write: a submit whose response we never saw is re-read
-        // here by the reference Meridian minted, never resubmitted blind.
-        statusEnquiry: {
-          keys: "provider_reference",
-          pathTemplate: "/v2/payments/{providerReference}",
-        },
-        // Meridian answers on the HTTP status and puts prose in the body of a
-        // failure, so a 4xx is the rejection and the body is for humans.
-        envelope: "http_status_error_body",
-        operation: "payout.submit",
-        obligationKind: "payout_submission",
-        resourceKind: "payout",
-        resourceIdPath: "payoutId",
-        direction: "tenant_initiated",
-        meter: "external_payout",
-      },
-      // The three endings. Nothing is sent for them: they record what the
-      // poll lane observed, so they carry no envelope of their own.
-      "payout.complete": {
-        operation: "payout.complete",
-        obligationKind: "payout_execution",
-        resourceKind: "payout",
-        resourceIdPath: "payoutId",
-        direction: "system_settlement",
-      },
-      "payout.fail": {
-        operation: "payout.fail",
-        obligationKind: "payout_execution",
-        resourceKind: "payout",
-        resourceIdPath: "payoutId",
-        direction: "system_settlement",
-      },
-      "payout.return": {
-        operation: "payout.return",
-        obligationKind: "payout_return",
-        resourceKind: "payout",
-        resourceIdPath: "payoutId",
-        direction: "system_settlement",
-      },
-    },
-    webhookMap: {
-      "payout.settled": {
-        eventKind: "payout.settled",
-        operationName: "payout.complete",
-        requiredPayloadFields: ["providerReference", "valueDate"],
-        optionalPayloadFields: ["chargeAmount"],
-        requiredFieldGroups: [],
-        resourceIdField: "payoutId",
-        resourceKind: "payout",
-        timestampField: "completedAt",
-      },
-    },
-    bindings: { payout: "claim" },
-    config: meridianConfig,
-    profile: meridianProfile,
-  },
-  {
-    provider: "meridian_bank",
-    capability: "bank_credit",
-    domain: "deposits",
-    // Incoming credits are learned by reading statements, so this capability
-    // sends Meridian nothing.
-    egress: "none",
-    operationMap: {
-      "deposit.record": {
-        operation: "deposit.record",
-        obligationKind: "bank_credit",
-        resourceKind: "deposit",
-        resourceIdPath: "depositId",
-        direction: "system_settlement",
-      },
-    },
-    webhookMap: {
-      "deposit.received": {
-        eventKind: "deposit.received",
-        operationName: "deposit.record",
-        requiredPayloadFields: ["financialAddressId", "amount", "currency"],
-        optionalPayloadFields: ["remitterName"],
-        requiredFieldGroups: [],
-        resourceIdField: "depositId",
-        resourceKind: "deposit",
-        timestampField: "receivedAt",
-      },
-    },
-    bindings: { deposit: "strict" },
-    config: meridianConfig,
-    profile: meridianProfile,
-  },
-]);