@peable.to/contracts 6.2.0 → 6.3.0

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.reportingRoutes = exports.downloadReportQuery = exports.listReportRunsQuery = exports.createReportRunParams = exports.reportRunSchema = exports.reportRunParametersSchema = exports.reportTypeSchema = void 0;
+exports.reportingRoutes = exports.downloadReportQuery = exports.listReportSchedulesQuery = exports.reportScheduleActionParams = exports.updateReportScheduleParams = exports.createReportScheduleParams = exports.listReportRunsQuery = exports.createReportRunParams = exports.reportScheduleSchema = exports.reportScheduleCadenceSchema = exports.reportRunSchema = exports.reportRunParametersSchema = exports.reportTypeSchema = void 0;
 const zod_1 = require("zod");
 const objects_1 = require("../../common/objects");
 const envelopes_1 = require("../../common/envelopes");
@@ -88,6 +88,7 @@ exports.reportRunSchema = (0, objects_2.defineObject)('reporting.report_run', 'R
         .nullable()
         .describe('The CSV once `succeeded` — a File of purpose `finance_report_run` (`GET /v1/files/{id}/contents` reads it).'),
     succeeded_at: primitives_1.unixSeconds.nullable(),
+    report_schedule: (0, objects_1.expandable)('reporting.report_schedule', 'The schedule that fired this run (`frs_…`); `null` for a run asked for directly.').nullable(),
 })
     .strict(), {
     examples: [
@@ -102,6 +103,78 @@ exports.reportRunSchema = (0, objects_2.defineObject)('reporting.report_run', 'R
             error: null,
             result: null,
             succeeded_at: null,
+            report_schedule: null,
+        },
+    ],
+});
+/** When a schedule fires (Stripe's payout-schedule spelling). */
+exports.reportScheduleCadenceSchema = (0, objects_2.defineComponent)('ReportScheduleCadence', zod_1.z
+    .object({
+    interval: zod_1.z.enum(reporting_1.REPORT_SCHEDULE_INTERVALS),
+    weekly_anchor: zod_1.z
+        .enum(reporting_1.REPORT_SCHEDULE_WEEKDAYS)
+        .nullable()
+        .describe('The day a `weekly` schedule fires; `null` otherwise.'),
+    monthly_anchor: zod_1.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.
+ */
+exports.reportScheduleSchema = (0, objects_2.defineObject)('reporting.report_schedule', 'ReportSchedule', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('reporting.report_schedule'),
+    livemode: primitives_1.livemode,
+    created: primitives_1.unixSeconds,
+    report_type: reportTypeId,
+    parameters: zod_1.z
+        .object({
+        columns: zod_1.z.array(zod_1.z.string()).optional(),
+        currency: primitives_1.currency.optional(),
+    })
+        .strict()
+        .describe("Every run's `parameters` but the interval, which each occurrence sets: the time since the previous occurrence."),
+    schedule: exports.reportScheduleCadenceSchema,
+    timezone: zod_1.z
+        .string()
+        .describe('The IANA time zone whose midnight each occurrence is (`Europe/Madrid`).'),
+    recipients: zod_1.z
+        .array(zod_1.z.string())
+        .describe('Who is emailed when a run of this schedule succeeds or fails.'),
+    locale: zod_1.z.enum(reporting_1.REPORT_SCHEDULE_LOCALES).describe('The language of those emails.'),
+    status: zod_1.z.enum(reporting_1.REPORT_SCHEDULE_STATUSES),
+    next_run_at: primitives_1.unixSeconds
+        .nullable()
+        .describe('The next occurrence while `active`; `null` while paused or canceled.'),
+    last_run: (0, objects_1.expandable)('reporting.report_run', 'The newest run this schedule fired.').nullable(),
+    canceled_at: primitives_1.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,
         },
     ],
 });
@@ -125,7 +198,79 @@ exports.createReportRunParams = zod_1.z
         .strict(),
 })
     .strict();
-exports.listReportRunsQuery = (0, params_1.listQuery)({ report_type: reportTypeId.optional() });
+exports.listReportRunsQuery = (0, params_1.listQuery)({
+    report_type: reportTypeId.optional(),
+    report_schedule: zod_1.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 = zod_1.z
+    .object({
+    columns: zod_1.z
+        .array(column)
+        .min(1)
+        .max(64)
+        .optional()
+        .describe("Columns of the report type's layout, each once."),
+    currency: zod_1.z.enum(money_1.CURRENCY_CODES).optional(),
+})
+    .strict();
+const cadenceParams = zod_1.z
+    .object({
+    interval: zod_1.z.enum(reporting_1.REPORT_SCHEDULE_INTERVALS),
+    weekly_anchor: zod_1.z
+        .enum(reporting_1.REPORT_SCHEDULE_WEEKDAYS)
+        .optional()
+        .describe('Required for `weekly`, refused otherwise.'),
+    monthly_anchor: zod_1.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 = zod_1.z
+    .array(zod_1.z.email().max(254))
+    .max(reporting_1.REPORT_SCHEDULE_MAX_RECIPIENTS)
+    .describe(`At most ${String(reporting_1.REPORT_SCHEDULE_MAX_RECIPIENTS)} addresses, each once. They receive a link to the run in Orbit, never the file.`);
+const timezoneParam = zod_1.z
+    .string()
+    .min(1)
+    .max(64)
+    .describe('An IANA time zone (`Europe/Madrid`); `UTC` when absent.');
+/** `POST /v1/reporting/report_schedules`. */
+exports.createReportScheduleParams = zod_1.z
+    .object({
+    report_type: reportTypeId,
+    parameters: scheduleParameters.optional(),
+    schedule: cadenceParams,
+    timezone: timezoneParam.optional(),
+    recipients: recipientsParam.optional(),
+    locale: zod_1.z.enum(reporting_1.REPORT_SCHEDULE_LOCALES).optional().describe('`en` when absent.'),
+})
+    .strict();
+/** `POST /v1/reporting/report_schedules/{id}`: each field sent replaces the stored one. */
+exports.updateReportScheduleParams = zod_1.z
+    .object({
+    report_type: reportTypeId.optional(),
+    parameters: scheduleParameters.optional(),
+    schedule: cadenceParams.optional(),
+    timezone: timezoneParam.optional(),
+    recipients: recipientsParam.optional(),
+    locale: zod_1.z.enum(reporting_1.REPORT_SCHEDULE_LOCALES).optional(),
+})
+    .strict();
+/** Pause, resume and cancel take no parameters. */
+exports.reportScheduleActionParams = zod_1.z.object({}).strict();
+exports.listReportSchedulesQuery = (0, params_1.listQuery)({
+    status: zod_1.z.enum(reporting_1.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`).
@@ -150,6 +295,7 @@ exports.downloadReportQuery = zod_1.z
 })
     .strict();
 const reportTypeIdParam = { id: 'The report type (`payments.itemized.1`, …).' };
+const reportScheduleIdParam = { id: 'The report schedule (`frs_…`).' };
 exports.reportingRoutes = [
     (0, route_1.defineRoute)({
         operationId: 'listReportTypes',
@@ -232,4 +378,106 @@ exports.reportingRoutes = [
         sdk: 'reporting.reportRuns.retrieve',
         expandable: 'reporting.report_run',
     }),
+    (0, route_1.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: exports.createReportScheduleParams,
+        response: exports.reportScheduleSchema,
+        sdk: 'reporting.reportSchedules.create',
+    }),
+    (0, route_1.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: exports.listReportSchedulesQuery,
+        response: (0, envelopes_1.listOf)(exports.reportScheduleSchema),
+        sdk: 'reporting.reportSchedules.list',
+        expandable: 'reporting.report_schedule',
+    }),
+    (0, route_1.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: params_1.expandOnlyQuery,
+        response: exports.reportScheduleSchema,
+        sdk: 'reporting.reportSchedules.retrieve',
+        expandable: 'reporting.report_schedule',
+    }),
+    (0, route_1.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: exports.updateReportScheduleParams,
+        response: exports.reportScheduleSchema,
+        sdk: 'reporting.reportSchedules.update',
+    }),
+    (0, route_1.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: exports.reportScheduleActionParams,
+        response: exports.reportScheduleSchema,
+        sdk: 'reporting.reportSchedules.pause',
+    }),
+    (0, route_1.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: exports.reportScheduleActionParams,
+        response: exports.reportScheduleSchema,
+        sdk: 'reporting.reportSchedules.resume',
+    }),
+    (0, route_1.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: exports.reportScheduleActionParams,
+        response: exports.reportScheduleSchema,
+        sdk: 'reporting.reportSchedules.cancel',
+    }),
 ];

package/dist/cjs/vocabulary/errors.js

@@ -122,6 +122,7 @@ exports.ERROR_CODE_DESCRIPTIONS = {
     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/cjs/vocabulary/reporting.js

@@ -3,7 +3,7 @@
 // run's lifecycle, and the methods and status classes a request log is
 // filtered by. Zod-free, like every vocabulary module.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REQUEST_LOG_RETENTION_DAYS = exports.REQUEST_LOG_STATUS_CLASSES = exports.REQUEST_LOG_METHODS = exports.REPORT_RUN_STATUSES = exports.REPORT_TYPE_IDS = void 0;
+exports.REPORT_SCHEDULE_MAX_RECIPIENTS = exports.REPORT_SCHEDULE_LOCALES = exports.REPORT_SCHEDULE_WEEKDAYS = exports.REPORT_SCHEDULE_INTERVALS = exports.REPORT_SCHEDULE_STATUSES = exports.REQUEST_LOG_RETENTION_DAYS = exports.REQUEST_LOG_STATUS_CLASSES = exports.REQUEST_LOG_METHODS = exports.REPORT_RUN_STATUSES = exports.REPORT_TYPE_IDS = void 0;
 /**
  * Every report Peable produces, by Stripe's versioned id: the trailing `.1` is
  * the column layout's version, so a layout can change under a new id without
@@ -25,3 +25,30 @@ exports.REQUEST_LOG_METHODS = ['GET', 'POST', 'DELETE', 'PATCH', 'PUT'];
 exports.REQUEST_LOG_STATUS_CLASSES = ['2xx', '3xx', '4xx', '5xx'];
 /** How long a request log is kept (and served). */
 exports.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.
+ */
+exports.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.
+ */
+exports.REPORT_SCHEDULE_INTERVALS = ['daily', 'weekly', 'monthly'];
+/** A weekly schedule's day, Monday first (ISO 8601). */
+exports.REPORT_SCHEDULE_WEEKDAYS = [
+    'monday',
+    'tuesday',
+    'wednesday',
+    'thursday',
+    'friday',
+    'saturday',
+    'sunday',
+];
+/** The languages a schedule's emails are written in — Orbit's own. */
+exports.REPORT_SCHEDULE_LOCALES = ['en', 'es'];
+/** How many addresses one schedule may email. */
+exports.REPORT_SCHEDULE_MAX_RECIPIENTS = 10;

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/vocabulary/errors.js

@@ -117,6 +117,7 @@ export const ERROR_CODE_DESCRIPTIONS = {
     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/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;