@peable.to/contracts 0.3.0 → 1.0.0

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

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { network, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { merchantDisplaySchema } from '../checkout/shared.js';
+/**
+ * The SELLER-facing half of FairCoin connected accounts (ADR 0012 D3).
+ *
+ * A platform mints an onboarding link for a seller's account; the SELLER opens
+ * it signed in with Oxy and registers the watch-only key their FairCoin will be
+ * paid to. These routes are `auth: 'user'` — the seller's own session, never a
+ * service token — because the key that decides who receives a seller's money is
+ * accepted only from the seller. A platform cannot reach them at all, and the
+ * link token alone is not enough without the session it names.
+ */
+export const connectOnboardingSchema = defineObject('connect_onboarding', 'ConnectOnboarding', z
+    .object({
+    object: z.literal('connect_onboarding'),
+    account_id: z.string().describe('The `ca_…` being onboarded.'),
+    // The platform's public display, as a payer would see it: never a
+    // webhook secret, never a key.
+    platform: merchantDisplaySchema.describe("Who is asking: the PLATFORM's public display, as a payer would see it."),
+    network: network.describe('The chain the seller will be paid on. Their key must be for it.'),
+    expires_at: unixSeconds.describe('When this link stops working.'),
+    return_url: z.string().describe('Where to send the seller once the key is registered.'),
+})
+    .strict());
+/** The answer to a successful registration. */
+export const connectOnboardingCompleteSchema = defineComponent('ConnectOnboardingComplete', z
+    .object({
+    object: z.literal('connect_onboarding'),
+    account_id: z.string(),
+    status: z.literal('active'),
+    return_url: z.string(),
+})
+    .strict());
+/**
+ * An extended public key is 111 characters in base58check; the bound is a
+ * request-size guard with headroom, not a format check — the non-custody
+ * firewall (`assertWatchOnly`) is.
+ */
+const XPUB_MAX_LENGTH = 200;
+/** `POST /v1/connect/onboarding/{token}/faircoin` — the seller's watch-only ACCOUNT xpub. */
+export const registerFaircoinKeyParams = z
+    .object({
+    xpub: z
+        .string()
+        .trim()
+        .min(1)
+        .max(XPUB_MAX_LENGTH)
+        .describe('A watch-only extended PUBLIC key. A private extended key is refused (`watch_only_violation`) and never stored.'),
+})
+    .strict();
+const tokenParam = { token: 'The onboarding link token (the last segment of its `url`).' };
+export const connectOnboardingRoutes = [
+    defineRoute({
+        operationId: 'retrieveConnectOnboarding',
+        method: 'get',
+        path: '/v1/connect/onboarding/{token}',
+        tag: 'Connect onboarding',
+        summary: 'Retrieve an onboarding link',
+        description: 'What the seller is being asked to do. Looking consumes nothing. An expired link answers 410 `link_expired` with the platform’s `refresh_url`.',
+        auth: 'user',
+        params: tokenParam,
+        response: connectOnboardingSchema,
+    }),
+    defineRoute({
+        operationId: 'registerConnectOnboardingFaircoinKey',
+        method: 'post',
+        path: '/v1/connect/onboarding/{token}/faircoin',
+        tag: 'Connect onboarding',
+        summary: "Register the seller's FairCoin key",
+        description: 'The ONLY way a key reaches a connected account: runs the non-custody firewall, consumes the link and tells the platform (`connected_account.updated`), in one transaction. The key is immutable once registered and never appears on any response.',
+        auth: 'user',
+        params: tokenParam,
+        body: registerFaircoinKeyParams,
+        response: connectOnboardingCompleteSchema,
+    }),
+];

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

@@ -0,0 +1,193 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { expandOnlyQuery, idParam, listQuery, metadataCreateParam } from '../../common/params.js';
+import { amount, livemode, metadata, signedAmount, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { PAYOUT_DESTINATION_TYPES, PAYOUT_METHODS, PAYOUT_RECONCILIATION_STATUSES, PAYOUT_STATUSES, } from '../../vocabulary/connect.js';
+import { CURRENCY_CODES, isBaseUnitString } from '../../vocabulary/money.js';
+import { balanceTransactionSchema } from './balance.js';
+/**
+ * Payouts (`po_…`) — the provider moving the merchant's balance to the
+ * merchant's bank (ADR 0015 §4). Executed by the provider, always; Orbit
+ * instructs (a manual payout) or mirrors (a scheduled one). The bank account
+ * itself stays at the provider and is never on this object.
+ */
+export const payoutSchema = defineObject('payout', 'Payout', z
+    .object({
+    id: z.string(),
+    object: z.literal('payout'),
+    livemode,
+    account: z.string().describe('The account (`ca_…`) paid out.'),
+    amount,
+    currency: z.string().describe('Upper-case ISO 4217 code.'),
+    status: z.enum(PAYOUT_STATUSES),
+    arrival_date: unixSeconds
+        .nullable()
+        .describe('When the funds are expected in the bank, as the provider estimates.'),
+    automatic: z
+        .boolean()
+        .describe("`true` when the provider's schedule created it, `false` for `POST /v1/payouts`."),
+    method: z.enum(PAYOUT_METHODS),
+    type: z.enum(PAYOUT_DESTINATION_TYPES),
+    description: z.string().nullable(),
+    statement_descriptor: z.string().nullable(),
+    failure_code: z
+        .string()
+        .nullable()
+        .describe("The provider's failure code when `failed`; never its prose."),
+    balance_transaction: z
+        .string()
+        .nullable()
+        .describe("The payout's own `txn_…` once ingested."),
+    metadata,
+    created: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'po_0193b8f31e2d4c5a9b60',
+            object: 'payout',
+            livemode: false,
+            account: 'ca_0193b8f2c1a87d3e9f4a',
+            amount: '150000',
+            currency: 'EUR',
+            status: 'in_transit',
+            arrival_date: 1793923200,
+            automatic: false,
+            method: 'standard',
+            type: 'bank_account',
+            description: 'November payout',
+            statement_descriptor: 'ROSEN PAYOUT',
+            failure_code: null,
+            balance_transaction: 'txn_0193b8f31f0a7e3d2c41',
+            metadata: {},
+            created: 1793750400,
+        },
+    ],
+});
+/**
+ * `GET /v1/reports/payout_reconciliation?payout=po_…` — the balance
+ * transactions one payout paid out, with their totals. A list page with the
+ * report's fields beside it.
+ */
+export const payoutReconciliationReportSchema = defineComponent('PayoutReconciliationReport', z
+    .object({
+    object: z.literal('list'),
+    data: z.array(balanceTransactionSchema),
+    has_more: z.boolean(),
+    url: z.string(),
+    payout: z.string().describe('The payout (`po_…`) reconciled.'),
+    status: z
+        .enum(PAYOUT_RECONCILIATION_STATUSES)
+        .describe('`complete` once the payout is `paid` and its transactions were read from the provider; `pending` before — the set is not final and the totals may grow.'),
+    currency: z.string(),
+    summary: z
+        .object({
+        count: z.number().int().nonnegative(),
+        amount: signedAmount,
+        fee: signedAmount,
+        net: signedAmount,
+    })
+        .strict()
+        .describe('Over EVERY transaction of the payout, not just this page.'),
+})
+    .strict());
+/** `POST /v1/payouts` — a payout instruction for an account on a manual schedule. */
+export const createPayoutParams = z
+    .object({
+    amount: z
+        .string()
+        .refine(isBaseUnitString, 'amount must be a minor-unit integer string')
+        .refine((value) => value !== '0', 'amount must be positive'),
+    currency: z.enum(CURRENCY_CODES),
+    description: z.string().max(1000).optional(),
+    statement_descriptor: z.string().min(1).max(22).optional(),
+    method: z.enum(PAYOUT_METHODS).optional().describe('Defaults to `standard`.'),
+    metadata: metadataCreateParam.optional(),
+})
+    .strict();
+export const listPayoutsQuery = listQuery({ status: z.enum(PAYOUT_STATUSES).optional() });
+/** `POST /v1/payouts/{id}/cancel` takes no parameters. */
+export const cancelPayoutParams = z.object({}).strict();
+export const payoutReconciliationQuery = listQuery({
+    payout: idParam.describe('The payout (`po_…`) to reconcile.'),
+});
+const payoutIdParam = { id: 'The payout (`po_…`).' };
+export const payoutRoutes = [
+    defineRoute({
+        operationId: 'listPayouts',
+        method: 'get',
+        path: '/v1/payouts',
+        tag: 'Payouts',
+        summary: 'List payouts',
+        auth: 'service',
+        scope: 'payments:read',
+        peableAccount: true,
+        query: listPayoutsQuery,
+        response: listOf(payoutSchema),
+        sdk: 'payouts.list',
+        expandable: 'payout',
+    }),
+    defineRoute({
+        operationId: 'createPayout',
+        method: 'post',
+        path: '/v1/payouts',
+        tag: 'Payouts',
+        summary: 'Create a payout',
+        description: 'An instruction to the provider, for an account on a `manual` payout schedule. The provider executes it; Orbit never moves the money itself.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        peableAccount: true,
+        body: createPayoutParams,
+        response: payoutSchema,
+        status: 201,
+        sdk: 'payouts.create',
+    }),
+    defineRoute({
+        operationId: 'retrievePayout',
+        method: 'get',
+        path: '/v1/payouts/{id}',
+        tag: 'Payouts',
+        summary: 'Retrieve a payout',
+        auth: 'service',
+        scope: 'payments:read',
+        peableAccount: true,
+        params: payoutIdParam,
+        query: expandOnlyQuery,
+        response: payoutSchema,
+        sdk: 'payouts.retrieve',
+    }),
+    defineRoute({
+        operationId: 'cancelPayout',
+        method: 'post',
+        path: '/v1/payouts/{id}/cancel',
+        tag: 'Payouts',
+        summary: 'Cancel a payout',
+        description: 'Only a manual payout the provider still allows to be canceled.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        peableAccount: true,
+        params: payoutIdParam,
+        body: cancelPayoutParams,
+        response: payoutSchema,
+        sdk: 'payouts.cancel',
+    }),
+    defineRoute({
+        operationId: 'retrievePayoutReconciliation',
+        method: 'get',
+        path: '/v1/reports/payout_reconciliation',
+        tag: 'Payouts',
+        summary: 'Reconcile a payout',
+        description: 'The balance transactions one payout paid out, a page at a time, with totals over all of them.',
+        auth: 'service',
+        scope: 'payments:read',
+        peableAccount: true,
+        query: payoutReconciliationQuery,
+        response: payoutReconciliationReportSchema,
+        sdk: 'reports.payoutReconciliation',
+        expandable: 'balance_transaction',
+    }),
+];

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

@@ -0,0 +1,232 @@
+import { z } from 'zod';
+import { embedded } 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';
+/**
+ * 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
+ * `file_…` of purpose `finance_report_run` — or downloads the same CSV at once,
+ * streamed (`GET /v1/reporting/report_types/{id}/csv`). Both are ONE report:
+ * the same layout, the same columns, the same computation. The layouts are
+ * `REPORT_TYPE_LAYOUTS` in `@peable.to/shared-types/reporting`.
+ */
+const reportTypeId = z.enum(REPORT_TYPE_IDS);
+/** `reporting.report_type` — what can be run, and over which interval data exists. */
+export const reportTypeSchema = defineObject('reporting.report_type', 'ReportType', z
+    .object({
+    id: reportTypeId.describe('`payments.itemized.1`, …; the trailing number is the layout version.'),
+    object: z.literal('reporting.report_type'),
+    livemode,
+    name: z.string(),
+    version: z
+        .number()
+        .int()
+        .describe("The column layout's version — the trailing number of the id."),
+    columns: z
+        .array(z.string())
+        .describe('Every column `parameters.columns` may name, in the order they are written.'),
+    default_columns: z.array(z.string()),
+    data_available_start: unixSeconds.describe('The earliest `interval_start` with data.'),
+    data_available_end: unixSeconds.describe('The latest `interval_end` a run may ask for: now — the data is live.'),
+    updated: unixSeconds.describe('When the layout last changed.'),
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'balance.summary.1',
+            object: 'reporting.report_type',
+            livemode: false,
+            name: 'Balance summary',
+            version: 1,
+            columns: [
+                'category',
+                'description',
+                'currency',
+                'net_amount',
+                'transaction_count',
+                'net_amount_decimal',
+            ],
+            default_columns: ['category', 'description', 'currency', 'net_amount'],
+            data_available_start: 1790000000,
+            data_available_end: 1793750400,
+            updated: 1793664000,
+        },
+    ],
+});
+/** What a run was asked to cover. */
+export const reportRunParametersSchema = defineComponent('ReportRunParameters', z
+    .object({
+    interval_start: unixSeconds.describe('Inclusive.'),
+    interval_end: unixSeconds.describe('Exclusive.'),
+    columns: z
+        .array(z.string())
+        .optional()
+        .describe("The columns, in the layout's order; the report type's `default_columns` when absent."),
+    currency: currency.optional().describe('Only this currency.'),
+})
+    .strict());
+/** `reporting.report_run` (`frr_…`). */
+export const reportRunSchema = defineObject('reporting.report_run', 'ReportRun', z
+    .object({
+    id: z.string(),
+    object: z.literal('reporting.report_run'),
+    livemode,
+    created: unixSeconds,
+    report_type: reportTypeId,
+    parameters: reportRunParametersSchema,
+    status: z.enum(REPORT_RUN_STATUSES),
+    error: z.string().nullable().describe('Why a `failed` run failed; `null` otherwise.'),
+    result: embedded('file')
+        .nullable()
+        .describe('The CSV once `succeeded` — a File of purpose `finance_report_run` (`GET /v1/files/{id}/contents` reads it).'),
+    succeeded_at: unixSeconds.nullable(),
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'frr_0193b8f34d1e4a6b8c27',
+            object: 'reporting.report_run',
+            livemode: false,
+            created: 1793750400,
+            report_type: 'balance.summary.1',
+            parameters: { interval_start: 1790985600, interval_end: 1793577600 },
+            status: 'pending',
+            error: null,
+            result: null,
+            succeeded_at: null,
+        },
+    ],
+});
+const column = z.string().min(1).max(64);
+/** `POST /v1/reporting/report_runs`. */
+export const createReportRunParams = z
+    .object({
+    report_type: reportTypeId,
+    parameters: z
+        .object({
+        interval_start: unixSecondsParam.describe('Inclusive, Unix seconds.'),
+        interval_end: unixSecondsParam.describe('Exclusive, Unix seconds; after `interval_start` and not in the future.'),
+        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(),
+})
+    .strict();
+export const listReportRunsQuery = listQuery({ report_type: reportTypeId.optional() });
+/**
+ * A download's query: a run's `parameters`, spelled as a query string
+ * (`columns[]=a&columns[]=b`, or one `columns=a`).
+ */
+export const downloadReportQuery = z
+    .object({
+    interval_start: queryInteger({ min: 0 }).describe('Inclusive, Unix seconds.'),
+    interval_end: queryInteger({ min: 0 }).describe('Exclusive, Unix seconds.'),
+    columns: describe(z
+        .union([z.string(), z.array(z.string())])
+        .transform((value) => (typeof value === 'string' ? [value] : value))
+        .pipe(z.array(column).min(1).max(64)), {
+        description: "Columns of the report type's layout, each once.",
+        jsonSchema: {
+            type: 'array',
+            items: { type: 'string', minLength: 1, maxLength: 64 },
+            minItems: 1,
+            maxItems: 64,
+        },
+    }).optional(),
+    currency: z.enum(CURRENCY_CODES).optional(),
+})
+    .strict();
+const reportTypeIdParam = { id: 'The report type (`payments.itemized.1`, …).' };
+export const reportingRoutes = [
+    defineRoute({
+        operationId: 'listReportTypes',
+        method: 'get',
+        path: '/v1/reporting/report_types',
+        tag: 'Reporting',
+        summary: 'List report types',
+        description: 'Every report Peable produces (a complete set), with the interval data exists for.',
+        auth: 'service',
+        scope: 'payments:read',
+        query: emptyQuery,
+        response: listOf(reportTypeSchema),
+        sdk: 'reporting.reportTypes.list',
+    }),
+    defineRoute({
+        operationId: 'retrieveReportType',
+        method: 'get',
+        path: '/v1/reporting/report_types/{id}',
+        tag: 'Reporting',
+        summary: 'Retrieve a report type',
+        auth: 'service',
+        scope: 'payments:read',
+        params: reportTypeIdParam,
+        query: emptyQuery,
+        response: reportTypeSchema,
+        sdk: 'reporting.reportTypes.retrieve',
+    }),
+    defineRoute({
+        operationId: 'downloadReport',
+        method: 'get',
+        path: '/v1/reporting/report_types/{id}/csv',
+        tag: 'Reporting',
+        summary: 'Download a report',
+        description: 'The same report a run produces, with the same parameters, streamed at once as CSV instead of stored. Every refusal is the JSON error before the first byte; a read that fails afterwards aborts the response, so a truncated file never ends cleanly.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: reportTypeIdParam,
+        query: downloadReportQuery,
+        response: { kind: 'binary', contentType: 'text/csv' },
+        sdk: 'reporting.reportTypes.download',
+    }),
+    defineRoute({
+        operationId: 'createReportRun',
+        method: 'post',
+        path: '/v1/reporting/report_runs',
+        tag: 'Reporting',
+        summary: 'Create a report run',
+        description: 'Answers `pending` at once; the CSV is produced in the background and announced with `reporting.report_run.succeeded` (or `.failed`).',
+        auth: 'service',
+        scope: 'payments:read',
+        idempotent: true,
+        body: createReportRunParams,
+        response: reportRunSchema,
+        sdk: 'reporting.reportRuns.create',
+    }),
+    defineRoute({
+        operationId: 'listReportRuns',
+        method: 'get',
+        path: '/v1/reporting/report_runs',
+        tag: 'Reporting',
+        summary: 'List report runs',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listReportRunsQuery,
+        response: listOf(reportRunSchema),
+        sdk: 'reporting.reportRuns.list',
+        expandable: 'reporting.report_run',
+    }),
+    defineRoute({
+        operationId: 'retrieveReportRun',
+        method: 'get',
+        path: '/v1/reporting/report_runs/{id}',
+        tag: 'Reporting',
+        summary: 'Retrieve a report run',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The report run (`frr_…`).' },
+        query: expandOnlyQuery,
+        response: reportRunSchema,
+        sdk: 'reporting.reportRuns.retrieve',
+        expandable: 'reporting.report_run',
+    }),
+];

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

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineObject } from '../../common/objects.js';
+import { expandOnlyQuery, listQuery, queryInteger } from '../../common/params.js';
+import { livemode, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { REQUEST_LOG_METHODS, REQUEST_LOG_STATUS_CLASSES } from '../../vocabulary/reporting.js';
+/**
+ * One merchant API request, as Peable recorded it (`req_…`) — the request log
+ * Orbit and `peable logs tail` read. Its `id` IS the `Request-Id` that request
+ * was answered with, so the id a merchant quotes to support and the log row
+ * are the same thing.
+ *
+ * Deliberately thin: method, path (no query string), status, duration and the
+ * `Idempotency-Key` it carried. No body, no headers, no query string, no caller
+ * address — a log a merchant can read is a log that must not hold what a
+ * request carried. Kept 30 days.
+ */
+export const requestLogSchema = defineObject('request_log', 'RequestLog', z
+    .object({
+    id: z.string().describe("The request's `Request-Id` (`req_…`)."),
+    object: z.literal('request_log'),
+    livemode,
+    method: z.enum(REQUEST_LOG_METHODS),
+    path: z.string().describe('The path that was requested, without its query string.'),
+    status: z.number().int().describe('The HTTP status it was answered with.'),
+    duration_ms: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe('How long the gateway took to answer, in milliseconds.'),
+    idempotency_key: z
+        .string()
+        .nullable()
+        .describe('The `Idempotency-Key` the request carried, if it carried a valid one.'),
+    created: unixSeconds.describe('When it was answered.'),
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'req_0193b8f35e9c4f2a7b18',
+            object: 'request_log',
+            livemode: false,
+            method: 'POST',
+            path: '/v1/payment_intents',
+            status: 201,
+            duration_ms: 84,
+            idempotency_key: '5f1d3c2e-8a4b-4f6e-9d2c-1b7a0e3f4c5d',
+            created: 1793750400,
+        },
+    ],
+});
+/** `status=404` (one code) or `status=4xx` (a class). */
+const requestLogStatusFilter = z
+    .union([queryInteger({ min: 100, max: 599 }), z.enum(REQUEST_LOG_STATUS_CLASSES)])
+    .describe('One status code (`404`) or a class (`2xx`, `3xx`, `4xx`, `5xx`).');
+const requestLogFilters = {
+    status: requestLogStatusFilter.optional(),
+    method: z.enum(REQUEST_LOG_METHODS).optional(),
+};
+export const listRequestLogsQuery = listQuery(requestLogFilters);
+/** The live tail's filters: the list's, without paging. */
+export const streamRequestLogsQuery = z.object(requestLogFilters).strict();
+export const requestLogRoutes = [
+    defineRoute({
+        operationId: 'listRequestLogs',
+        method: 'get',
+        path: '/v1/request_logs',
+        tag: 'Request logs',
+        summary: 'List request logs',
+        description: 'Your API requests of the last 30 days, newest first, filtered by `status`, `method` and `created`.',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listRequestLogsQuery,
+        response: listOf(requestLogSchema),
+        sdk: 'requestLogs.list',
+        expandable: 'request_log',
+    }),
+    defineRoute({
+        operationId: 'streamRequestLogs',
+        method: 'get',
+        path: '/v1/request_logs/stream',
+        tag: 'Request logs',
+        summary: 'Stream request logs',
+        description: 'Server-Sent Events: each request as it is answered (`event: request_log`), after a `ready` event. Reconnect with `Last-Event-ID` to resume without a gap. Test mode only; a stream ends after 15 minutes.',
+        auth: 'service',
+        scope: 'payments:read',
+        testModeOnly: true,
+        query: streamRequestLogsQuery,
+        response: { kind: 'stream', event: requestLogSchema },
+        sdk: 'requestLogs.stream',
+    }),
+    defineRoute({
+        operationId: 'retrieveRequestLog',
+        method: 'get',
+        path: '/v1/request_logs/{id}',
+        tag: 'Request logs',
+        summary: 'Retrieve a request log',
+        description: 'By `Request-Id`; 404 once older than 30 days.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The `Request-Id` (`req_…`).' },
+        query: expandOnlyQuery,
+        response: requestLogSchema,
+        sdk: 'requestLogs.retrieve',
+    }),
+];