@peable.to/contracts 6.1.0 → 6.3.0

package/dist/esm/resources/connect/reporting.js

@@ -1,12 +1,12 @@
 import { z } from 'zod';
-import { embedded } from '../../common/objects.js';
+import { embedded, expandable } from '../../common/objects.js';
 import { listOf } from '../../common/envelopes.js';
 import { defineComponent, defineObject, describe } from '../../common/objects.js';
 import { emptyQuery, expandOnlyQuery, listQuery, queryInteger, unixSecondsParam, } from '../../common/params.js';
 import { currency, livemode, unixSeconds } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
 import { CURRENCY_CODES } from '../../vocabulary/money.js';
-import { REPORT_RUN_STATUSES, REPORT_TYPE_IDS } from '../../vocabulary/reporting.js';
+import { REPORT_RUN_STATUSES, REPORT_SCHEDULE_INTERVALS, REPORT_SCHEDULE_LOCALES, REPORT_SCHEDULE_MAX_RECIPIENTS, REPORT_SCHEDULE_STATUSES, REPORT_SCHEDULE_WEEKDAYS, REPORT_TYPE_IDS, } from '../../vocabulary/reporting.js';
 /**
  * Reporting (Stripe's `reporting.*`): a merchant asks for a report over an
  * interval, Peable computes it in the background and stores the CSV as a
@@ -85,6 +85,7 @@ export const reportRunSchema = defineObject('reporting.report_run', 'ReportRun',
         .nullable()
         .describe('The CSV once `succeeded` — a File of purpose `finance_report_run` (`GET /v1/files/{id}/contents` reads it).'),
     succeeded_at: unixSeconds.nullable(),
+    report_schedule: expandable('reporting.report_schedule', 'The schedule that fired this run (`frs_…`); `null` for a run asked for directly.').nullable(),
 })
     .strict(), {
     examples: [
@@ -99,6 +100,78 @@ export const reportRunSchema = defineObject('reporting.report_run', 'ReportRun',
             error: null,
             result: null,
             succeeded_at: null,
+            report_schedule: null,
+        },
+    ],
+});
+/** When a schedule fires (Stripe's payout-schedule spelling). */
+export const reportScheduleCadenceSchema = defineComponent('ReportScheduleCadence', z
+    .object({
+    interval: z.enum(REPORT_SCHEDULE_INTERVALS),
+    weekly_anchor: z
+        .enum(REPORT_SCHEDULE_WEEKDAYS)
+        .nullable()
+        .describe('The day a `weekly` schedule fires; `null` otherwise.'),
+    monthly_anchor: z
+        .number()
+        .int()
+        .nullable()
+        .describe('The day of the month a `monthly` schedule fires (1–31; a shorter month fires on its last day); `null` otherwise.'),
+})
+    .strict());
+/**
+ * `reporting.report_schedule` (`frs_…`): a report run on a cadence. Each
+ * occurrence is local midnight in `timezone`; it creates an ordinary report
+ * run over the time since the previous occurrence, and emails `recipients` a
+ * link to it in Orbit once it succeeded (or failed). The CSV is never attached
+ * and never public: a recipient signs in to Orbit to download it.
+ */
+export const reportScheduleSchema = defineObject('reporting.report_schedule', 'ReportSchedule', z
+    .object({
+    id: z.string(),
+    object: z.literal('reporting.report_schedule'),
+    livemode,
+    created: unixSeconds,
+    report_type: reportTypeId,
+    parameters: z
+        .object({
+        columns: z.array(z.string()).optional(),
+        currency: currency.optional(),
+    })
+        .strict()
+        .describe("Every run's `parameters` but the interval, which each occurrence sets: the time since the previous occurrence."),
+    schedule: reportScheduleCadenceSchema,
+    timezone: z
+        .string()
+        .describe('The IANA time zone whose midnight each occurrence is (`Europe/Madrid`).'),
+    recipients: z
+        .array(z.string())
+        .describe('Who is emailed when a run of this schedule succeeds or fails.'),
+    locale: z.enum(REPORT_SCHEDULE_LOCALES).describe('The language of those emails.'),
+    status: z.enum(REPORT_SCHEDULE_STATUSES),
+    next_run_at: unixSeconds
+        .nullable()
+        .describe('The next occurrence while `active`; `null` while paused or canceled.'),
+    last_run: expandable('reporting.report_run', 'The newest run this schedule fired.').nullable(),
+    canceled_at: unixSeconds.nullable(),
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'frs_0193b8f34d1e4a6b8c27',
+            object: 'reporting.report_schedule',
+            livemode: false,
+            created: 1793750400,
+            report_type: 'balance.summary.1',
+            parameters: {},
+            schedule: { interval: 'monthly', weekly_anchor: null, monthly_anchor: 1 },
+            timezone: 'Europe/Madrid',
+            recipients: ['finance@example.com'],
+            locale: 'en',
+            status: 'active',
+            next_run_at: 1796079600,
+            last_run: null,
+            canceled_at: null,
         },
     ],
 });
@@ -122,7 +195,79 @@ export const createReportRunParams = z
         .strict(),
 })
     .strict();
-export const listReportRunsQuery = listQuery({ report_type: reportTypeId.optional() });
+export const listReportRunsQuery = listQuery({
+    report_type: reportTypeId.optional(),
+    report_schedule: z
+        .string()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe('Only the runs this schedule (`frs_…`) fired.'),
+});
+/** A schedule's run template: a run's `parameters` without the interval. */
+const scheduleParameters = z
+    .object({
+    columns: z
+        .array(column)
+        .min(1)
+        .max(64)
+        .optional()
+        .describe("Columns of the report type's layout, each once."),
+    currency: z.enum(CURRENCY_CODES).optional(),
+})
+    .strict();
+const cadenceParams = z
+    .object({
+    interval: z.enum(REPORT_SCHEDULE_INTERVALS),
+    weekly_anchor: z
+        .enum(REPORT_SCHEDULE_WEEKDAYS)
+        .optional()
+        .describe('Required for `weekly`, refused otherwise.'),
+    monthly_anchor: z
+        .number()
+        .int()
+        .min(1)
+        .max(31)
+        .optional()
+        .describe('Required for `monthly`, refused otherwise; a shorter month fires on its last day.'),
+})
+    .strict();
+const recipientsParam = z
+    .array(z.email().max(254))
+    .max(REPORT_SCHEDULE_MAX_RECIPIENTS)
+    .describe(`At most ${String(REPORT_SCHEDULE_MAX_RECIPIENTS)} addresses, each once. They receive a link to the run in Orbit, never the file.`);
+const timezoneParam = z
+    .string()
+    .min(1)
+    .max(64)
+    .describe('An IANA time zone (`Europe/Madrid`); `UTC` when absent.');
+/** `POST /v1/reporting/report_schedules`. */
+export const createReportScheduleParams = z
+    .object({
+    report_type: reportTypeId,
+    parameters: scheduleParameters.optional(),
+    schedule: cadenceParams,
+    timezone: timezoneParam.optional(),
+    recipients: recipientsParam.optional(),
+    locale: z.enum(REPORT_SCHEDULE_LOCALES).optional().describe('`en` when absent.'),
+})
+    .strict();
+/** `POST /v1/reporting/report_schedules/{id}`: each field sent replaces the stored one. */
+export const updateReportScheduleParams = z
+    .object({
+    report_type: reportTypeId.optional(),
+    parameters: scheduleParameters.optional(),
+    schedule: cadenceParams.optional(),
+    timezone: timezoneParam.optional(),
+    recipients: recipientsParam.optional(),
+    locale: z.enum(REPORT_SCHEDULE_LOCALES).optional(),
+})
+    .strict();
+/** Pause, resume and cancel take no parameters. */
+export const reportScheduleActionParams = z.object({}).strict();
+export const listReportSchedulesQuery = listQuery({
+    status: z.enum(REPORT_SCHEDULE_STATUSES).optional(),
+});
 /**
  * A download's query: a run's `parameters`, spelled as a query string
  * (`columns[]=a&columns[]=b`, or one `columns=a`).
@@ -147,6 +292,7 @@ export const downloadReportQuery = z
 })
     .strict();
 const reportTypeIdParam = { id: 'The report type (`payments.itemized.1`, …).' };
+const reportScheduleIdParam = { id: 'The report schedule (`frs_…`).' };
 export const reportingRoutes = [
     defineRoute({
         operationId: 'listReportTypes',
@@ -229,4 +375,106 @@ export const reportingRoutes = [
         sdk: 'reporting.reportRuns.retrieve',
         expandable: 'reporting.report_run',
     }),
+    defineRoute({
+        operationId: 'createReportSchedule',
+        method: 'post',
+        path: '/v1/reporting/report_schedules',
+        tag: 'Reporting',
+        summary: 'Create a report schedule',
+        description: 'A report run at local midnight in `timezone` every day, week or month, each over the time since the previous occurrence. `next_run_at` is the first occurrence after now; nothing is backfilled.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createReportScheduleParams,
+        response: reportScheduleSchema,
+        sdk: 'reporting.reportSchedules.create',
+    }),
+    defineRoute({
+        operationId: 'listReportSchedules',
+        method: 'get',
+        path: '/v1/reporting/report_schedules',
+        tag: 'Reporting',
+        summary: 'List report schedules',
+        description: 'Newest first; a canceled schedule is listed too.',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listReportSchedulesQuery,
+        response: listOf(reportScheduleSchema),
+        sdk: 'reporting.reportSchedules.list',
+        expandable: 'reporting.report_schedule',
+    }),
+    defineRoute({
+        operationId: 'retrieveReportSchedule',
+        method: 'get',
+        path: '/v1/reporting/report_schedules/{id}',
+        tag: 'Reporting',
+        summary: 'Retrieve a report schedule',
+        auth: 'service',
+        scope: 'payments:read',
+        params: reportScheduleIdParam,
+        query: expandOnlyQuery,
+        response: reportScheduleSchema,
+        sdk: 'reporting.reportSchedules.retrieve',
+        expandable: 'reporting.report_schedule',
+    }),
+    defineRoute({
+        operationId: 'updateReportSchedule',
+        method: 'post',
+        path: '/v1/reporting/report_schedules/{id}',
+        tag: 'Reporting',
+        summary: 'Update a report schedule',
+        description: 'A new `schedule` or `timezone` moves an active schedule to its first occurrence after now. A canceled schedule cannot change (409 `report_schedule_unexpected_state`).',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: reportScheduleIdParam,
+        body: updateReportScheduleParams,
+        response: reportScheduleSchema,
+        sdk: 'reporting.reportSchedules.update',
+    }),
+    defineRoute({
+        operationId: 'pauseReportSchedule',
+        method: 'post',
+        path: '/v1/reporting/report_schedules/{id}/pause',
+        tag: 'Reporting',
+        summary: 'Pause a report schedule',
+        description: 'Nothing fires until it is resumed. Pausing a paused schedule answers it as it is.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: reportScheduleIdParam,
+        body: reportScheduleActionParams,
+        response: reportScheduleSchema,
+        sdk: 'reporting.reportSchedules.pause',
+    }),
+    defineRoute({
+        operationId: 'resumeReportSchedule',
+        method: 'post',
+        path: '/v1/reporting/report_schedules/{id}/resume',
+        tag: 'Reporting',
+        summary: 'Resume a paused report schedule',
+        description: 'It fires again from its first occurrence after now; the occurrences it missed while paused are not run.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: reportScheduleIdParam,
+        body: reportScheduleActionParams,
+        response: reportScheduleSchema,
+        sdk: 'reporting.reportSchedules.resume',
+    }),
+    defineRoute({
+        operationId: 'cancelReportSchedule',
+        method: 'post',
+        path: '/v1/reporting/report_schedules/{id}/cancel',
+        tag: 'Reporting',
+        summary: 'Cancel a report schedule',
+        description: 'For good: it never fires again, and a run it fires no longer emails anyone. Its runs and their files stay.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: reportScheduleIdParam,
+        body: reportScheduleActionParams,
+        response: reportScheduleSchema,
+        sdk: 'reporting.reportSchedules.cancel',
+    }),
 ];

package/dist/esm/resources/events/events.js

@@ -270,6 +270,10 @@ export const WEBHOOK_EVENT_DESCRIPTIONS = {
     'billing_portal.configuration.created': 'A customer portal configuration was created.',
     'billing_portal.configuration.updated': 'A customer portal configuration was updated.',
     'billing_portal.session.created': 'A customer portal session was created.',
+    'quote.created': 'A draft Quote was created.',
+    'quote.finalized': 'A Quote was finalized: numbered, priced and taxed, waiting for its customer.',
+    'quote.accepted': 'A Quote was accepted: its `invoice` (and, for recurring lines, its `subscription`) exists.',
+    'quote.canceled': 'A Quote was cancelled, or expired while open.',
     'tax.assessment.created': 'A tax compliance assessment was run. Nothing was registered, filed or collected.',
     'tax.review_item.created': 'A tax assessment finding opened a review item.',
     'tax.review_item.updated': 'A tax review item was decided, or found again.',

package/dist/esm/vocabulary/errors.js

@@ -112,8 +112,12 @@ export const ERROR_CODE_DESCRIPTIONS = {
     invoice_not_editable: 'The invoice is finalized and can no longer be edited.',
     invoice_unexpected_state: 'The invoice is in a status that does not allow this operation.',
     invoice_no_customer_line_items: 'The invoice has no line items to finalize.',
+    quote_not_editable: 'Only a draft quote can be edited.',
+    quote_unexpected_state: "The quote's status does not allow this.",
+    quote_expired: 'The quote expired.',
     invoice_payment_intent_requires_action: "The invoice's payment needs the customer to act (a card challenge).",
     subscription_unexpected_state: 'The subscription is in a status that does not allow this operation.',
+    report_schedule_unexpected_state: 'A canceled report schedule never changes.',
     customer_currency_mismatch: "The currency differs from the customer's billing currency.",
     customer_test_clock_mismatch: 'The objects live on different test clocks.',
     coupon_invalid: 'The coupon does not exist or is no longer valid.',

package/dist/esm/vocabulary/events.js

@@ -120,6 +120,10 @@ export const WEBHOOK_EVENT_OBJECTS = {
     'billing_portal.configuration.created': 'billing_portal.configuration',
     'billing_portal.configuration.updated': 'billing_portal.configuration',
     'billing_portal.session.created': 'billing_portal.session',
+    'quote.created': 'quote',
+    'quote.finalized': 'quote',
+    'quote.accepted': 'quote',
+    'quote.canceled': 'quote',
     'tax.assessment.created': 'tax.assessment',
     'tax.review_item.created': 'tax.review_item',
     'tax.review_item.updated': 'tax.review_item',

package/dist/esm/vocabulary/index.js

@@ -13,6 +13,7 @@ export * from './lists.js';
 export * from './money.js';
 export * from './tax.js';
 export * from './subscriptions.js';
+export * from './quotes.js';
 export * from './reporting.js';
 export * from './payments.js';
 export * from './version.js';

package/dist/esm/vocabulary/invoices.js

@@ -10,6 +10,9 @@ export const INVOICE_BILLING_REASONS = [
     'subscription_update',
     'subscription_cancel',
     'upcoming',
+    // A one-time quote's invoice (Stripe's name); a recurring quote's first
+    // invoice is its subscription's `subscription_create`.
+    'quote_accept',
 ];
 /**
  * `automatic_tax.status` — Peable Tax (ADR 0011) is computed before an invoice

package/dist/esm/vocabulary/quotes.js

@@ -0,0 +1,28 @@
+// Quotes (`qt_…`, ADR 0018 §5) — the closed value sets their schemas are built
+// from. Zod-free: `@peable.to/shared-types` re-exports them at runtime.
+/**
+ * Where a quote stands — Stripe's four.
+ *
+ *  - `draft`    — being written; the only status a quote can be edited in.
+ *  - `open`     — finalized: numbered, priced and taxed, waiting for the
+ *                 customer's answer until `expires_at`.
+ *  - `accepted` — terminal: the native billing engine made its invoice (one-time
+ *                 lines) or its subscription and first invoice (recurring lines).
+ *  - `canceled` — terminal: cancelled by the merchant, or expired while open.
+ */
+export const QUOTE_STATUSES = ['draft', 'open', 'accepted', 'canceled'];
+/** Bounds a quote is checked against. */
+export const QUOTE_LIMITS = {
+    /** Lines on one quote — a subscription's item limit. */
+    lineItemsMax: 20,
+    quantityMax: 1000000,
+    /** `header` and `footer`; `description` is 1500 like an invoice's. */
+    headerMax: 50,
+    footerMax: 500,
+    descriptionMax: 1500,
+    /** A quote expires 30 days after it is created unless `expires_at` says otherwise (Stripe's default). */
+    defaultExpiryDays: 30,
+    /** `expires_at` at most this far ahead. */
+    expiryMaxDays: 365,
+    trialPeriodDaysMax: 730,
+};

package/dist/esm/vocabulary/reporting.js

@@ -22,3 +22,30 @@ export const REQUEST_LOG_METHODS = ['GET', 'POST', 'DELETE', 'PATCH', 'PUT'];
 export const REQUEST_LOG_STATUS_CLASSES = ['2xx', '3xx', '4xx', '5xx'];
 /** How long a request log is kept (and served). */
 export const REQUEST_LOG_RETENTION_DAYS = 30;
+/**
+ * A report schedule's lifecycle: `active` fires at each occurrence, `paused`
+ * fires nothing until resumed (resuming never backfills), `canceled` is
+ * terminal.
+ */
+export const REPORT_SCHEDULE_STATUSES = ['active', 'paused', 'canceled'];
+/**
+ * How often a schedule fires — Stripe's payout-schedule spelling: every day,
+ * once a week on `weekly_anchor`, once a month on `monthly_anchor`. Each
+ * occurrence is local midnight in the schedule's timezone, and its run covers
+ * the time since the previous occurrence.
+ */
+export const REPORT_SCHEDULE_INTERVALS = ['daily', 'weekly', 'monthly'];
+/** A weekly schedule's day, Monday first (ISO 8601). */
+export const REPORT_SCHEDULE_WEEKDAYS = [
+    'monday',
+    'tuesday',
+    'wednesday',
+    'thursday',
+    'friday',
+    'saturday',
+    'sunday',
+];
+/** The languages a schedule's emails are written in — Orbit's own. */
+export const REPORT_SCHEDULE_LOCALES = ['en', 'es'];
+/** How many addresses one schedule may email. */
+export const REPORT_SCHEDULE_MAX_RECIPIENTS = 10;