@peable.to/contracts 0.4.0 → 1.1.0

package/dist/esm/openapi/document.js

@@ -0,0 +1,294 @@
+import { z } from 'zod';
+import { errorEnvelopeSchema } from '../common/envelopes.js';
+import { contractRegistry } from '../common/objects.js';
+import { isJsonResponse, pathParamNames } from '../route.js';
+import { routes } from '../routes.js';
+import { PEABLE_API_VERSION } from '../vocabulary/version.js';
+import { webhookEvents } from './webhooks.js';
+const COMPONENT_PREFIX = '#/components/schemas/';
+/** Apply the registry's documentation (`jsonSchema` replacements, `x-peable-expandable`) to a generated node. */
+function override(ctx) {
+    const meta = contractRegistry.get(ctx.zodSchema);
+    const global = 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 = z.toJSONSchema(schema, {
+        target: 'draft-2020-12',
+        metadata: 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 = 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: 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 = 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 \`${PEABLE_API_VERSION}\` exists.`,
+        schema: { type: 'string', enum: [PEABLE_API_VERSION] },
+    });
+    const status = String(route.status ?? 200);
+    const response = route.response;
+    let content;
+    if (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(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. */
+export function buildOpenApiDocument() {
+    var _a;
+    collected.clear();
+    const paths = {};
+    const tags = new Set();
+    for (const route of 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 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: 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/esm/openapi/index.js

@@ -0,0 +1,2 @@
+export { buildOpenApiDocument } from './document.js';
+export { webhookEvents } from './webhooks.js';

package/dist/esm/openapi/webhooks.js

@@ -0,0 +1,14 @@
+import { eventSchemaOf, WEBHOOK_EVENT_DESCRIPTIONS } from '../resources/events/events.js';
+import { WEBHOOK_EVENT_TYPES } from '../vocabulary/events.js';
+/**
+ * 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.
+ */
+export function webhookEvents() {
+    return WEBHOOK_EVENT_TYPES.map((type) => ({
+        type,
+        description: WEBHOOK_EVENT_DESCRIPTIONS[type],
+        schema: eventSchemaOf(type),
+    }));
+}

package/dist/esm/resources/billingEngine/billingPortal.js

@@ -0,0 +1,234 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { expandOnlyQuery, idParam, listQuery, metadataCreateParam, metadataUpdateParam, queryBoolean, } from '../../common/params.js';
+import { livemode, metadata, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { PORTAL_CANCEL_MODES, PORTAL_CANCEL_PRORATION_BEHAVIORS, PORTAL_CUSTOMER_UPDATES, PORTAL_SUBSCRIPTION_UPDATES, } from '../../vocabulary/billingPortal.js';
+import { PRORATION_BEHAVIORS } from '../../vocabulary/subscriptions.js';
+import { httpUrlParam, shortText } from './params.js';
+/**
+ * The customer portal's merchant side (ADR 0018 §9): configurations (`bpc_…`)
+ * say what the Orbit-hosted portal lets a customer do; a session (`bps_…`) is
+ * a short-lived URL for ONE customer.
+ */
+/** What the hosted portal lets a customer do. */
+export const billingPortalFeaturesSchema = defineComponent('BillingPortalFeatures', z
+    .object({
+    customer_update: z
+        .object({
+        enabled: z.boolean(),
+        allowed_updates: z.array(z.enum(PORTAL_CUSTOMER_UPDATES)),
+    })
+        .strict(),
+    invoice_history: z.object({ enabled: z.boolean() }).strict(),
+    payment_method_update: z.object({ enabled: z.boolean() }).strict(),
+    subscription_cancel: z
+        .object({
+        enabled: z.boolean(),
+        mode: z.enum(PORTAL_CANCEL_MODES),
+        proration_behavior: z.enum(PORTAL_CANCEL_PRORATION_BEHAVIORS),
+    })
+        .strict(),
+    subscription_update: z
+        .object({
+        enabled: z.boolean(),
+        default_allowed_updates: z.array(z.enum(PORTAL_SUBSCRIPTION_UPDATES)),
+        proration_behavior: z.enum(PRORATION_BEHAVIORS),
+        products: z
+            .array(z.object({ product: z.string(), prices: z.array(z.string()) }).strict())
+            .describe('The plans a customer may switch between: per product, its allowed prices.'),
+    })
+        .strict(),
+})
+    .strict());
+/** The business the portal presents. */
+export const billingPortalBusinessProfileSchema = defineComponent('BillingPortalBusinessProfile', z
+    .object({
+    headline: z.string().nullable(),
+    privacy_policy_url: z.string().nullable(),
+    terms_of_service_url: z.string().nullable(),
+})
+    .strict());
+export const billingPortalConfigurationSchema = defineObject('billing_portal.configuration', 'BillingPortalConfiguration', z
+    .object({
+    id: z.string(),
+    object: z.literal('billing_portal.configuration'),
+    livemode,
+    active: z.boolean(),
+    is_default: z
+        .boolean()
+        .describe('The configuration a session uses when it names none (created on first use).'),
+    business_profile: billingPortalBusinessProfileSchema,
+    default_return_url: z.string().nullable(),
+    features: billingPortalFeaturesSchema,
+    metadata,
+    created: unixSeconds,
+    updated: unixSeconds,
+})
+    .strict());
+/**
+ * A portal session: a short-lived URL for ONE customer. The URL is a bearer
+ * credential — hand it to that customer only, right away. It is answered once
+ * and never stored.
+ */
+export const billingPortalSessionSchema = defineObject('billing_portal.session', 'BillingPortalSession', z
+    .object({
+    id: z.string(),
+    object: z.literal('billing_portal.session'),
+    livemode,
+    customer: z.string().describe('The customer (`cus_…`) the portal is for.'),
+    configuration: z.string().describe('The configuration (`bpc_…`) it applies.'),
+    return_url: z.string().nullable(),
+    url: z.string().describe('The portal, for this customer only. A bearer credential.'),
+    expires_at: unixSeconds.describe('The URL stops working after this instant.'),
+    created: unixSeconds,
+})
+    .strict());
+// ---- Requests ------------------------------------------------------------------------
+const businessProfileParams = z
+    .object({
+    headline: shortText(60).optional(),
+    privacy_policy_url: httpUrlParam.optional(),
+    terms_of_service_url: httpUrlParam.optional(),
+})
+    .strict();
+/** Each named feature field replaces that field; the others keep their value (or default). */
+const featuresParams = z
+    .object({
+    customer_update: z
+        .object({
+        enabled: z.boolean().optional(),
+        allowed_updates: z.array(z.enum(PORTAL_CUSTOMER_UPDATES)).max(4).optional(),
+    })
+        .strict()
+        .optional(),
+    invoice_history: z.object({ enabled: z.boolean() }).strict().optional(),
+    payment_method_update: z.object({ enabled: z.boolean() }).strict().optional(),
+    subscription_cancel: z
+        .object({
+        enabled: z.boolean().optional(),
+        mode: z.enum(PORTAL_CANCEL_MODES).optional(),
+        proration_behavior: z.enum(PORTAL_CANCEL_PRORATION_BEHAVIORS).optional(),
+    })
+        .strict()
+        .optional(),
+    subscription_update: z
+        .object({
+        enabled: z.boolean().optional(),
+        default_allowed_updates: z.array(z.enum(PORTAL_SUBSCRIPTION_UPDATES)).max(2).optional(),
+        proration_behavior: z.enum(PRORATION_BEHAVIORS).optional(),
+        products: z
+            .array(z.object({ product: idParam, prices: z.array(idParam).min(1).max(10) }).strict())
+            .max(10)
+            .optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+export const createBillingPortalConfigurationParams = z
+    .object({
+    business_profile: businessProfileParams.optional(),
+    default_return_url: httpUrlParam.optional(),
+    features: featuresParams,
+    metadata: metadataCreateParam.optional(),
+})
+    .strict();
+/** A field sent as `""` is cleared; `metadata` is a patch. */
+export const updateBillingPortalConfigurationParams = z
+    .object({
+    active: z.boolean().optional().describe('The default configuration cannot be deactivated.'),
+    business_profile: businessProfileParams.optional(),
+    default_return_url: z.union([httpUrlParam, z.literal('')]).optional(),
+    features: featuresParams.optional(),
+    metadata: metadataUpdateParam.optional(),
+})
+    .strict();
+export const listBillingPortalConfigurationsQuery = listQuery({
+    active: queryBoolean.optional(),
+    is_default: queryBoolean.optional(),
+});
+export const createBillingPortalSessionParams = z
+    .object({
+    customer: idParam,
+    configuration: idParam
+        .optional()
+        .describe("Default: the merchant's default configuration (created on first use)."),
+    return_url: httpUrlParam.optional(),
+})
+    .strict();
+// ---- Routes --------------------------------------------------------------------------
+const configurationId = { id: 'The portal configuration (`bpc_…`).' };
+export const billingPortalRoutes = [
+    defineRoute({
+        operationId: 'createBillingPortalConfiguration',
+        method: 'post',
+        path: '/v1/billing_portal/configurations',
+        tag: 'Customer portal',
+        summary: 'Create a portal configuration',
+        description: "Features not named take the safe defaults. The merchant's first configuration becomes the default.",
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createBillingPortalConfigurationParams,
+        response: billingPortalConfigurationSchema,
+        sdk: 'billingPortal.configurations.create',
+    }),
+    defineRoute({
+        operationId: 'listBillingPortalConfigurations',
+        method: 'get',
+        path: '/v1/billing_portal/configurations',
+        tag: 'Customer portal',
+        summary: 'List portal configurations',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listBillingPortalConfigurationsQuery,
+        response: listOf(billingPortalConfigurationSchema),
+        sdk: 'billingPortal.configurations.list',
+        expandable: 'billing_portal.configuration',
+    }),
+    defineRoute({
+        operationId: 'retrieveBillingPortalConfiguration',
+        method: 'get',
+        path: '/v1/billing_portal/configurations/{id}',
+        tag: 'Customer portal',
+        summary: 'Retrieve a portal configuration',
+        auth: 'service',
+        scope: 'payments:read',
+        params: configurationId,
+        query: expandOnlyQuery,
+        response: billingPortalConfigurationSchema,
+        sdk: 'billingPortal.configurations.retrieve',
+        expandable: 'billing_portal.configuration',
+    }),
+    defineRoute({
+        operationId: 'updateBillingPortalConfiguration',
+        method: 'post',
+        path: '/v1/billing_portal/configurations/{id}',
+        tag: 'Customer portal',
+        summary: 'Update a portal configuration',
+        description: 'Each named feature field replaces that field; the others are kept.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: configurationId,
+        body: updateBillingPortalConfigurationParams,
+        response: billingPortalConfigurationSchema,
+        sdk: 'billingPortal.configurations.update',
+    }),
+    defineRoute({
+        operationId: 'createBillingPortalSession',
+        method: 'post',
+        path: '/v1/billing_portal/sessions',
+        tag: 'Customer portal',
+        summary: 'Create a portal session',
+        description: 'A one-hour URL of the Orbit-hosted portal for one customer. The URL is a bearer credential: hand it to that customer only, right away.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createBillingPortalSessionParams,
+        response: billingPortalSessionSchema,
+        sdk: 'billingPortal.sessions.create',
+    }),
+];