@peable.to/contracts 0.4.0 → 1.1.0

package/dist/cjs/index.js

@@ -1,139 +1,42 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.contributionPatchSchema = exports.contributionOperationKeySchema = exports.contributionMintSchema = exports.contributionPageQuerySchema = exports.listQueryShape = exports.contributionCollectionListSchema = exports.contributionCollectionSchema = exports.contributionListSchema = exports.contributionLinkSchema = exports.createContributionSchema = exports.contributionDetailsSchema = exports.contributionAmountSchema = void 0;
-exports.decimalContributionAmount = decimalContributionAmount;
-exports.formatContributionAmount = formatContributionAmount;
-const zod_1 = require("zod");
-exports.contributionAmountSchema = zod_1.z
-    .string()
-    .regex(/^[1-9][0-9]{0,15}$/)
-    .refine((v) => /^[1-9][0-9]{0,15}$/.test(v) && BigInt(v) <= 9007199254740991n, 'Enter a positive FairCoin base-unit amount within the supported range');
-/** Every instant on the wire is integer Unix seconds (ADR 0014 D1). */
-const unixSecondsSchema = zod_1.z.number().int().nonnegative();
-exports.contributionDetailsSchema = zod_1.z
-    .object({
-    organization_id: zod_1.z.string().min(1).max(200),
-    purpose: zod_1.z.string().trim().min(1).max(500),
-    amount_mode: zod_1.z.enum(['fixed', 'free']),
-    expires_at: unixSecondsSchema.nullable(),
-})
-    .strict();
-exports.createContributionSchema = zod_1.z
-    .object({
-    purpose: exports.contributionDetailsSchema.shape.purpose,
-    amount_mode: exports.contributionDetailsSchema.shape.amount_mode,
-    amount: exports.contributionAmountSchema.optional(),
-    currency: zod_1.z.literal('FAIR'),
-    expires_at: unixSecondsSchema.nullable().optional(),
-})
-    .strict()
-    .refine((v) => (v.amount_mode === 'free' ? v.amount === undefined : v.amount !== undefined), 'Fixed contributions require an amount; free contributions omit it');
-exports.contributionLinkSchema = zod_1.z
-    .object({
-    id: zod_1.z.string(),
-    object: zod_1.z.literal('payment_link'),
-    amount: zod_1.z.string(),
-    currency: zod_1.z.literal('FAIR'),
-    network: zod_1.z.enum(['mainnet', 'testnet']),
-    active: zod_1.z.boolean(),
-    url: zod_1.z.url(),
-    contribution: exports.contributionDetailsSchema,
-    created: unixSecondsSchema,
-})
-    .strict();
-/**
- * The one list envelope (ADR 0014 D1): `url` is the path that was listed.
- */
-function listSchema(item) {
-    return zod_1.z
-        .object({
-        object: zod_1.z.literal('list'),
-        data: zod_1.z.array(item),
-        has_more: zod_1.z.boolean(),
-        url: zod_1.z.string(),
-    })
-        .strict();
-}
-exports.contributionListSchema = listSchema(exports.contributionLinkSchema);
-exports.contributionCollectionSchema = zod_1.z
-    .object({
-    id: zod_1.z.string(),
-    object: zod_1.z.literal('payment_intent'),
-    amount: zod_1.z.string(),
-    currency: zod_1.z.literal('FAIR'),
-    status: zod_1.z.string(),
-    created: unixSecondsSchema,
-    refund_capability: zod_1.z.literal('unsupported_non_custodial'),
-    refunds: zod_1.z.array(zod_1.z
-        .object({
-        id: zod_1.z.string(),
-        object: zod_1.z.literal('refund'),
-        amount: zod_1.z.string(),
-        status: zod_1.z.string(),
-        created: unixSecondsSchema,
-    })
-        .strict()),
-})
-    .strict();
-exports.contributionCollectionListSchema = listSchema(exports.contributionCollectionSchema);
-const unixSecondsQuery = zod_1.z.coerce.number().int().nonnegative();
-/**
- * The list parameters every list accepts (ADR 0014 D1), newest first:
- *
- * - `limit` 1–100, default 10;
- * - `starting_after` — the id of the last object of the previous page — or
- *   `ending_before` — the id of the first object of the current one, which
- *   pages backwards and still answers newest first. Never both;
- * - `created` (one second) or `created[gt|gte|lt|lte]`, Unix seconds.
- *
- * Cursors are resolved by the gateway inside the caller's scope; one naming
- * anything else is a 400 with `param` naming the cursor.
- */
-exports.listQueryShape = {
-    limit: zod_1.z.coerce.number().int().min(1).max(100).default(10),
-    starting_after: zod_1.z.string().min(1).max(255).optional(),
-    ending_before: zod_1.z.string().min(1).max(255).optional(),
-    created: zod_1.z
-        .union([
-        unixSecondsQuery.transform((x) => ({ gte: x, lte: x })),
-        zod_1.z
-            .object({
-            gt: unixSecondsQuery.optional(),
-            gte: unixSecondsQuery.optional(),
-            lt: unixSecondsQuery.optional(),
-            lte: unixSecondsQuery.optional(),
-        })
-            .strict(),
-    ])
-        .optional(),
+// @peable.to/contracts — the Peable wire, declared once (ADR 0014 D5).
+//
+// Every public route's request and response schema is a Zod schema here. The
+// backend validates with these exact objects, the OpenAPI document
+// (`@peable.to/contracts/openapi`) is generated from them, `@peable.to/shared-types`
+// re-exports their inferred types, and `@peable.to/sdk`'s resource methods are
+// generated from the route list.
+//
+// Importing this root constructs every schema. A bundle that only needs the
+// closed value sets imports `@peable.to/contracts/vocabulary`.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
-/**
- * Paging a contribution list: the list parameters (`link_…` cursors for links,
- * `pi_…` for collections) plus the environment the Test/Live toggle selects.
- */
-exports.contributionPageQuerySchema = zod_1.z
-    .object({
-    ...exports.listQueryShape,
-    environment: zod_1.z.enum(['development', 'staging', 'production']),
-})
-    .strict()
-    .refine((query) => query.starting_after === undefined || query.ending_before === undefined, {
-    message: 'starting_after and ending_before are mutually exclusive',
-    path: ['ending_before'],
-});
-exports.contributionMintSchema = zod_1.z
-    .object({ amount: exports.contributionAmountSchema.optional() })
-    .strict();
-exports.contributionOperationKeySchema = zod_1.z.string().uuid();
-exports.contributionPatchSchema = zod_1.z.object({ active: zod_1.z.boolean() }).strict();
-function decimalContributionAmount(value) {
-    if (!/^(0|[1-9][0-9]{0,7})(\.[0-9]{1,8})?$/.test(value))
-        throw new Error('Enter a FAIR amount with at most eight decimals');
-    const [whole = '0', fraction = ''] = value.split('.');
-    return exports.contributionAmountSchema.parse((BigInt(whole) * 100000000n + BigInt(fraction.padEnd(8, '0'))).toString());
-}
-function formatContributionAmount(value) {
-    const units = BigInt(value);
-    const fraction = (units % 100000000n).toString().padStart(8, '0').replace(/0+$/, '');
-    return (units / 100000000n).toString() + (fraction ? `.${fraction}` : '');
-}
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./common/address"), exports);
+__exportStar(require("./common/envelopes"), exports);
+__exportStar(require("./common/objects"), exports);
+__exportStar(require("./common/params"), exports);
+__exportStar(require("./common/primitives"), exports);
+__exportStar(require("./route"), exports);
+__exportStar(require("./routes"), exports);
+__exportStar(require("./vocabulary"), exports);
+__exportStar(require("./resources/core"), exports);
+__exportStar(require("./resources/payments"), exports);
+__exportStar(require("./resources/checkout"), exports);
+__exportStar(require("./resources/catalog"), exports);
+__exportStar(require("./resources/billingEngine"), exports);
+__exportStar(require("./resources/connect"), exports);
+__exportStar(require("./resources/tax"), exports);
+__exportStar(require("./resources/events"), exports);

package/dist/cjs/openapi/document.js

@@ -0,0 +1,297 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOpenApiDocument = buildOpenApiDocument;
+const zod_1 = require("zod");
+const envelopes_1 = require("../common/envelopes");
+const objects_1 = require("../common/objects");
+const route_1 = require("../route");
+const routes_1 = require("../routes");
+const version_1 = require("../vocabulary/version");
+const webhooks_1 = require("./webhooks");
+const COMPONENT_PREFIX = '#/components/schemas/';
+/** Apply the registry's documentation (`jsonSchema` replacements, `x-peable-expandable`) to a generated node. */
+function override(ctx) {
+    const meta = objects_1.contractRegistry.get(ctx.zodSchema);
+    const global = zod_1.z.globalRegistry.get(ctx.zodSchema);
+    if (meta?.jsonSchema) {
+        for (const key of Object.keys(ctx.jsonSchema))
+            delete ctx.jsonSchema[key];
+        Object.assign(ctx.jsonSchema, meta.jsonSchema);
+    }
+    const description = meta?.description ?? global?.description;
+    if (description !== undefined && ctx.jsonSchema.description === undefined)
+        ctx.jsonSchema.description = description;
+    if (meta?.['x-peable-expandable'] !== undefined)
+        ctx.jsonSchema['x-peable-expandable'] = meta['x-peable-expandable'];
+    if (meta?.examples !== undefined)
+        ctx.jsonSchema.examples = [...meta.examples];
+    // `jsonSchema`/`id` are registry bookkeeping, never document fields.
+    delete ctx.jsonSchema.jsonSchema;
+    delete ctx.jsonSchema.id;
+}
+function toJson(schema, io) {
+    const json = zod_1.z.toJSONSchema(schema, {
+        target: 'draft-2020-12',
+        metadata: objects_1.contractRegistry,
+        io,
+        unrepresentable: 'any',
+        reused: 'inline',
+        cycles: 'ref',
+        override,
+    });
+    delete json.$schema;
+    return hoistDefinitions(json);
+}
+/** Every `$defs` entry produced while converting one schema, by component name. */
+const collected = new Map();
+/**
+ * `z.toJSONSchema` puts the registered objects a schema reaches into its own
+ * `$defs` and points at them with `#/components/schemas/<id>`; lift them into
+ * the document's components once.
+ */
+function hoistDefinitions(json) {
+    const defs = json.$defs;
+    delete json.$defs;
+    const rewritten = rewriteRefs(json);
+    if (defs) {
+        for (const [id, def] of Object.entries(defs)) {
+            if (id.startsWith('__schema'))
+                throw new Error(`an unregistered recursive schema produced '${id}'; register it with defineComponent`);
+            if (!collected.has(id))
+                collected.set(id, rewriteRefs(def));
+        }
+    }
+    return rewritten;
+}
+/** `#/$defs/<id>` → `#/components/schemas/<id>`, everywhere in a node. */
+function rewriteRefs(value) {
+    if (Array.isArray(value))
+        return value.map(rewriteRefs);
+    if (value === null || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, inner]) => [
+        key,
+        key === '$ref' && typeof inner === 'string'
+            ? inner.replace(/^#\/\$defs\//, COMPONENT_PREFIX)
+            : rewriteRefs(inner),
+    ]));
+}
+/** The JSON Schema of a registered component, or the inline one. */
+function schemaRef(schema, io) {
+    const id = objects_1.contractRegistry.get(schema)?.id;
+    if (id !== undefined) {
+        if (!collected.has(id)) {
+            // A registered root converts to a `$ref` plus its own definition in
+            // `$defs`, which `hoistDefinitions` has just collected under `id`.
+            const json = toJson(schema, io);
+            if (!collected.has(id)) {
+                delete json.$id;
+                collected.set(id, json);
+            }
+        }
+        return { $ref: `${COMPONENT_PREFIX}${id}` };
+    }
+    return toJson(schema, io);
+}
+const requestIdHeader = {
+    'Request-Id': {
+        description: 'Identifies this request to Peable support.',
+        schema: { type: 'string' },
+    },
+    'Peable-Version': {
+        description: 'The date of the wire this answer is spelled in.',
+        schema: { type: 'string', example: version_1.PEABLE_API_VERSION },
+    },
+};
+const SECURITY = {
+    service: [{ oxyServiceToken: [] }],
+    user: [{ oxyUserSession: [] }],
+    public: [],
+};
+/** A query schema's properties as OpenAPI parameters. */
+function queryParameters(query) {
+    const json = toJson(query, 'input');
+    const properties = (json.properties ?? {});
+    const required = new Set(json.required ?? []);
+    return Object.entries(properties).map(([name, schema]) => {
+        const { description, ...rest } = schema;
+        const isArray = rest.type === 'array';
+        const isObject = rest.type === 'object' || Array.isArray(rest.oneOf);
+        return {
+            in: 'query',
+            name: isArray ? `${name}[]` : name,
+            ...(required.has(name) ? { required: true } : {}),
+            ...(description === undefined ? {} : { description }),
+            ...(isObject ? { style: 'deepObject', explode: true } : {}),
+            schema: rest,
+        };
+    });
+}
+function operation(route) {
+    const parameters = (0, route_1.pathParamNames)(route.path).map((name) => ({
+        in: 'path',
+        name,
+        required: true,
+        ...(route.params?.[name] === undefined ? {} : { description: route.params[name] }),
+        schema: { type: 'string' },
+    }));
+    if (route.query)
+        parameters.push(...queryParameters(route.query));
+    if (route.idempotent)
+        parameters.push({
+            in: 'header',
+            name: 'Idempotency-Key',
+            description: 'Makes a retry safe: the same key with the same request answers the stored response for 24 hours (ADR 0014 D3). The SDK sends one on every POST.',
+            schema: { type: 'string', maxLength: 255 },
+        });
+    if (route.peableAccount)
+        parameters.push({
+            in: 'header',
+            name: 'Peable-Account',
+            description: 'A platform acting on one of its connected accounts (`ca_…`).',
+            schema: { type: 'string' },
+        });
+    parameters.push({
+        in: 'header',
+        name: 'Peable-Version',
+        description: `The wire date the caller was written against. Only \`${version_1.PEABLE_API_VERSION}\` exists.`,
+        schema: { type: 'string', enum: [version_1.PEABLE_API_VERSION] },
+    });
+    const status = String(route.status ?? 200);
+    const response = route.response;
+    let content;
+    if ((0, route_1.isJsonResponse)(response)) {
+        content = { 'application/json': { schema: schemaRef(response, 'output') } };
+    }
+    else if (response.kind === 'binary') {
+        content = { [response.contentType]: { schema: { type: 'string', format: 'binary' } } };
+    }
+    else {
+        content = {
+            'text/event-stream': {
+                schema: { type: 'string' },
+                'x-peable-event': schemaRef(response.event, 'output'),
+            },
+        };
+    }
+    return {
+        operationId: route.operationId,
+        tags: [route.tag],
+        summary: route.summary,
+        ...(route.description === undefined ? {} : { description: route.description }),
+        security: SECURITY[route.auth],
+        ...(route.scope === undefined ? {} : { 'x-peable-scope': route.scope }),
+        ...(route.sdk === undefined ? {} : { 'x-peable-sdk': route.sdk }),
+        ...(route.expandable === undefined ? {} : { 'x-peable-expandable': route.expandable }),
+        ...(route.testModeOnly ? { 'x-peable-test-mode-only': true } : {}),
+        parameters,
+        ...(route.body
+            ? {
+                requestBody: {
+                    required: true,
+                    content: {
+                        [route.bodyEncoding === 'multipart' ? 'multipart/form-data' : 'application/json']: {
+                            schema: toJson(route.body, 'input'),
+                        },
+                    },
+                },
+            }
+            : {}),
+        responses: {
+            [status]: {
+                description: 'Success',
+                headers: requestIdHeader,
+                ...(status === '204' ? {} : { content }),
+            },
+            default: {
+                description: 'The error envelope; the HTTP status and `error.type` identify the failure.',
+                headers: requestIdHeader,
+                content: { 'application/json': { schema: schemaRef(envelopes_1.errorEnvelopeSchema, 'output') } },
+            },
+        },
+    };
+}
+/** Sort an object's keys, recursively, so the document is byte-stable. */
+function sortKeys(value, depth = 0) {
+    if (Array.isArray(value))
+        return value.map((item) => sortKeys(item, depth + 1));
+    if (value === null || typeof value !== 'object')
+        return value;
+    const entries = Object.entries(value);
+    // Only component and path maps are sorted: a schema's own key order (type
+    // before properties) reads better as generated.
+    return Object.fromEntries(entries.map(([k, v]) => [k, sortKeys(v, depth + 1)]));
+}
+/** Generate the whole document. Pure: the same contracts give the same bytes. */
+function buildOpenApiDocument() {
+    var _a;
+    collected.clear();
+    const paths = {};
+    const tags = new Set();
+    for (const route of routes_1.routes) {
+        paths[_a = route.path] ?? (paths[_a] = {});
+        const methods = paths[route.path];
+        if (methods[route.method] !== undefined)
+            throw new Error(`${route.method.toUpperCase()} ${route.path} is declared twice`);
+        methods[route.method] = operation(route);
+        tags.add(route.tag);
+    }
+    const webhooks = {};
+    for (const event of (0, webhooks_1.webhookEvents)()) {
+        webhooks[event.type] = {
+            post: {
+                operationId: `webhook_${event.type.replace(/[^a-z0-9]+/g, '_')}`,
+                summary: event.type,
+                ...(event.description === undefined ? {} : { description: event.description }),
+                tags: ['Webhook events'],
+                parameters: [
+                    {
+                        in: 'header',
+                        name: 'Peable-Signature',
+                        required: true,
+                        description: '`t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`, one `v1=` per active secret while a secret is rolling. Verify with `peable.webhooks.constructEvent`.',
+                        schema: { type: 'string' },
+                    },
+                ],
+                requestBody: {
+                    required: true,
+                    content: { 'application/json': { schema: schemaRef(event.schema, 'output') } },
+                },
+                responses: { '2XX': { description: 'Acknowledged. Anything else is retried.' } },
+            },
+        };
+        tags.add('Webhook events');
+    }
+    const schemas = Object.fromEntries([...collected.entries()].sort(([a], [b]) => a.localeCompare(b)));
+    return sortKeys({
+        openapi: '3.1.0',
+        info: {
+            title: 'Peable API',
+            version: version_1.PEABLE_API_VERSION,
+            description: 'The Peable payments API (Orbit): FairCoin and card payments, Checkout, Payment Links, Billing, Connect and Tax. Amounts are base-unit integer strings; instants are Unix seconds; every object carries `id`, `object` and `livemode`. Guides: https://oxy.so/developers/docs/peable/.',
+            contact: { name: 'Peable', url: 'https://oxy.so/developers/docs/peable/' },
+            license: { name: 'MIT', identifier: 'MIT' },
+        },
+        servers: [{ url: 'https://api.peable.to', description: 'Production (test and live modes)' }],
+        tags: [...tags].sort().map((name) => ({ name })),
+        paths: Object.fromEntries(Object.entries(paths).sort(([a], [b]) => a.localeCompare(b))),
+        webhooks: Object.fromEntries(Object.entries(webhooks).sort(([a], [b]) => a.localeCompare(b))),
+        components: {
+            securitySchemes: {
+                oxyServiceToken: {
+                    type: 'http',
+                    scheme: 'bearer',
+                    bearerFormat: 'Oxy service token (EdDSA JWT)',
+                    description: "Your server's Oxy service token, minted from its application credential. `@peable.to/sdk` mints and refreshes it for you.",
+                },
+                oxyUserSession: {
+                    type: 'http',
+                    scheme: 'bearer',
+                    bearerFormat: 'Oxy user session',
+                    description: 'A signed-in Oxy user (the Peable app, an Oxy app acting for its user).',
+                },
+            },
+            schemas,
+        },
+    });
+}

package/dist/cjs/openapi/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webhookEvents = exports.buildOpenApiDocument = void 0;
+var document_1 = require("./document");
+Object.defineProperty(exports, "buildOpenApiDocument", { enumerable: true, get: function () { return document_1.buildOpenApiDocument; } });
+var webhooks_1 = require("./webhooks");
+Object.defineProperty(exports, "webhookEvents", { enumerable: true, get: function () { return webhooks_1.webhookEvents; } });

package/dist/cjs/openapi/webhooks.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webhookEvents = webhookEvents;
+const events_1 = require("../resources/events/events");
+const events_2 = require("../vocabulary/events");
+/**
+ * Every event type the gateway emits, with its payload: one entry per member
+ * of `WEBHOOK_EVENT_TYPES`, its body the `Event` envelope with `type` fixed and
+ * `data.object` the object `WEBHOOK_EVENT_OBJECTS` names.
+ */
+function webhookEvents() {
+    return events_2.WEBHOOK_EVENT_TYPES.map((type) => ({
+        type,
+        description: events_1.WEBHOOK_EVENT_DESCRIPTIONS[type],
+        schema: (0, events_1.eventSchemaOf)(type),
+    }));
+}