@peable.to/shared-types 0.16.0 → 0.17.0

package/dist/cjs/file.js

@@ -3,7 +3,7 @@
 // (ADR 0016: Orbit owns the object; the storage is Oxy Files, a binding that
 // never reaches the wire). Stripe's Files API, with Oxy Files underneath.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FILE_PURPOSE_POLICIES = exports.FILE_STATUSES = exports.FILE_TYPES = exports.FILE_PURPOSES = void 0;
+exports.FILE_PURPOSE_POLICIES = exports.FILE_STATUSES = exports.FILE_TYPES = exports.FILE_UPLOAD_PURPOSES = exports.FILE_PURPOSES = void 0;
 /**
  * What a file is FOR. Decided at upload and never changed: the purpose is what
  * sets the type and size policy, who may see the bytes, and which objects may
@@ -15,9 +15,22 @@ exports.FILE_PURPOSES = [
     'business_logo',
     'identity_document',
     'additional_verification',
+    'finance_report_run',
+];
+/**
+ * The purposes a merchant may upload or import. `finance_report_run` is not
+ * among them: a report's CSV is written by Peable's report runs
+ * (`/v1/reporting/report_runs`) and nobody else, so a file of that purpose is
+ * always a report Peable produced.
+ */
+exports.FILE_UPLOAD_PURPOSES = [
+    'dispute_evidence',
+    'business_logo',
+    'identity_document',
+    'additional_verification',
 ];
 /** The stored format, by its conventional extension (Stripe's `type`). */
-exports.FILE_TYPES = ['pdf', 'png', 'jpg'];
+exports.FILE_TYPES = ['pdf', 'png', 'jpg', 'csv'];
 /**
  * Whether the bytes can be used right now.
  *
@@ -29,16 +42,18 @@ exports.FILE_TYPES = ['pdf', 'png', 'jpg'];
  */
 exports.FILE_STATUSES = ['available', 'withheld', 'removed'];
 /**
- * The upload policy of each purpose: the formats it takes, recognised from the
- * bytes and never from a client's `Content-Type`, and the largest file.
+ * The policy of each purpose: the formats it takes, recognised from the bytes
+ * and never from a client's `Content-Type`, and the largest file.
  *
  * The provider's own ceilings, restated where the upload is parsed, so a file
  * the card network would refuse is refused at upload — not at the one-shot
- * dispute submission it was meant for.
+ * dispute submission it was meant for. `finance_report_run` is Peable's own
+ * output (see {@link FILE_UPLOAD_PURPOSES}); its ceiling bounds a report.
  */
 exports.FILE_PURPOSE_POLICIES = Object.freeze({
     dispute_evidence: { types: ['pdf', 'png', 'jpg'], max_bytes: 5 * 1024 * 1024 },
     business_logo: { types: ['png', 'jpg'], max_bytes: 512 * 1024 },
     identity_document: { types: ['pdf', 'png', 'jpg'], max_bytes: 10 * 1024 * 1024 },
     additional_verification: { types: ['pdf', 'png', 'jpg'], max_bytes: 10 * 1024 * 1024 },
+    finance_report_run: { types: ['csv'], max_bytes: 64 * 1024 * 1024 },
 });

package/dist/cjs/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PAYOUT_STATUSES = exports.BALANCE_TRANSACTION_TYPES = exports.BALANCE_TRANSACTION_STATUSES = exports.PAYOUT_WEEKLY_ANCHORS = exports.PAYOUT_INTERVALS = exports.PAYMENT_METHOD_CURRENCIES = exports.PAYMENT_METHOD_CONFIGURATION_TYPES = exports.CARD_RAIL_PAYMENT_METHOD_TYPES = exports.FILE_TYPES = exports.FILE_STATUSES = exports.FILE_PURPOSE_POLICIES = exports.FILE_PURPOSES = exports.normalizeDisputeReason = exports.DISPUTE_TEXT_EVIDENCE_FIELDS = exports.DISPUTE_REASONS = exports.DISPUTE_FILE_EVIDENCE_FIELDS = exports.CATALOG_LIMITS = exports.COUPON_DURATIONS = exports.TRANSFORM_QUANTITY_ROUNDS = exports.PRICE_TAX_BEHAVIORS = exports.RECURRING_USAGE_TYPES = exports.RECURRING_INTERVALS = exports.PRICE_TYPES = exports.PRICE_TIERS_MODES = exports.PRICE_BILLING_SCHEMES = exports.WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS = exports.WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = exports.WEBHOOK_ENDPOINT_DISABLED_REASONS = exports.WEBHOOK_ENDPOINT_STATUSES = exports.PEABLE_API_VERSION = exports.SETUP_INTENT_STATUSES = exports.isValidStatusTransition = exports.canStillBePaid = exports.canExpire = exports.TERMINAL_STATUSES = exports.PAYMENT_INTENT_STATUSES = exports.PAYMENT_INTENT_SETUP_FUTURE_USAGES = exports.PAYMENT_INTENT_RAILS = exports.PAYMENT_INTENT_CAPTURE_METHODS = exports.PAYMENT_INTENT_CANCELLATION_REASONS = exports.MERCHANT_CANCELLATION_REASONS = exports.EXPIRABLE_STATUSES = exports.CARD_ONLY_STATUSES = exports.isCurrencyCode = exports.decimalsFor = exports.FIAT_CURRENCY_CODES = exports.CURRENCY_DECIMALS = exports.CURRENCY_CODES = exports.isBaseUnitString = exports.UNITS_PER_COIN = void 0;
-exports.TAX_LOCATION_EVIDENCE_TYPES = exports.TAX_REGISTRATION_SCHEMES = exports.PEABLE_BILLING_AUTHORITY_KEYS = exports.canonicalBillingTaxQuote = exports.canonicalBillingAuthority = exports.BILLING_SUBSCRIPTION_STATUSES = exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = exports.DEFAULT_BRANDING = exports.BRANDING_COLOR_PATTERN = exports.BRANDING_BORDER_STYLES = exports.BRANDING_FONTS = exports.CHECKOUT_SESSION_ID_TEMPLATE = exports.CHECKOUT_LIMITS = exports.CHECKOUT_TAX_ID_TYPES = exports.CHECKOUT_CUSTOM_FIELD_TYPES = exports.CHECKOUT_BILLING_ADDRESS_COLLECTIONS = exports.CHECKOUT_CUSTOMER_CREATIONS = exports.CHECKOUT_SUBMIT_TYPES = exports.CHECKOUT_LOCALES = exports.CHECKOUT_UI_MODES = exports.CHECKOUT_PAYMENT_STATUSES = exports.CHECKOUT_SESSION_STATUSES = exports.CHECKOUT_SESSION_MODES = exports.PAYMENT_LINK_LIMITS = exports.MERCHANT_ENVIRONMENTS = exports.verifyWebhook = exports.signWebhook = exports.SIMULATED_FAIRCOIN_OUTCOMES = exports.REQUEST_LOG_RETENTION_DAYS = exports.REQUEST_LOG_METHODS = exports.REFUND_REASONS = exports.RECONCILIATION_MISMATCH_KINDS = void 0;
+exports.REPORT_TYPE_LAYOUTS = exports.REPORT_TYPE_IDS = exports.REPORT_RUN_STATUSES = exports.SEARCH_SUBSTRING_MIN_LENGTH = exports.SEARCH_QUERY_MAX_LENGTH = exports.SEARCH_QUERY_MAX_CLAUSES = exports.SEARCHABLE_RESOURCES = exports.FILE_TYPES = exports.FILE_STATUSES = exports.FILE_UPLOAD_PURPOSES = exports.FILE_PURPOSE_POLICIES = exports.FILE_PURPOSES = exports.normalizeDisputeReason = exports.DISPUTE_TEXT_EVIDENCE_FIELDS = exports.DISPUTE_REASONS = exports.DISPUTE_FILE_EVIDENCE_FIELDS = exports.CATALOG_LIMITS = exports.COUPON_DURATIONS = exports.TRANSFORM_QUANTITY_ROUNDS = exports.PRICE_TAX_BEHAVIORS = exports.RECURRING_USAGE_TYPES = exports.RECURRING_INTERVALS = exports.PRICE_TYPES = exports.PRICE_TIERS_MODES = exports.PRICE_BILLING_SCHEMES = exports.WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS = exports.WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = exports.WEBHOOK_ENDPOINT_DISABLED_REASONS = exports.WEBHOOK_ENDPOINT_STATUSES = exports.PEABLE_API_VERSION = exports.SETUP_INTENT_STATUSES = exports.isValidStatusTransition = exports.canStillBePaid = exports.canExpire = exports.TERMINAL_STATUSES = exports.PAYMENT_INTENT_STATUSES = exports.PAYMENT_INTENT_SETUP_FUTURE_USAGES = exports.PAYMENT_INTENT_RAILS = exports.PAYMENT_INTENT_CAPTURE_METHODS = exports.PAYMENT_INTENT_CANCELLATION_REASONS = exports.MERCHANT_CANCELLATION_REASONS = exports.EXPIRABLE_STATUSES = exports.CARD_ONLY_STATUSES = exports.isCurrencyCode = exports.decimalsFor = exports.FIAT_CURRENCY_CODES = exports.CURRENCY_DECIMALS = exports.CURRENCY_CODES = exports.isBaseUnitString = exports.UNITS_PER_COIN = void 0;
+exports.TAX_LOCATION_EVIDENCE_TYPES = exports.TAX_REGISTRATION_SCHEMES = exports.PEABLE_BILLING_AUTHORITY_KEYS = exports.canonicalBillingTaxQuote = exports.canonicalBillingAuthority = exports.BILLING_SUBSCRIPTION_STATUSES = exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = exports.DEFAULT_BRANDING = exports.BRANDING_COLOR_PATTERN = exports.BRANDING_BORDER_STYLES = exports.BRANDING_FONTS = exports.CHECKOUT_SESSION_ID_TEMPLATE = exports.CHECKOUT_LIMITS = exports.CHECKOUT_TAX_ID_TYPES = exports.CHECKOUT_CUSTOM_FIELD_TYPES = exports.CHECKOUT_BILLING_ADDRESS_COLLECTIONS = exports.CHECKOUT_CUSTOMER_CREATIONS = exports.CHECKOUT_SUBMIT_TYPES = exports.CHECKOUT_LOCALES = exports.CHECKOUT_UI_MODES = exports.CHECKOUT_PAYMENT_STATUSES = exports.CHECKOUT_SESSION_STATUSES = exports.CHECKOUT_SESSION_MODES = exports.PAYMENT_LINK_LIMITS = exports.MERCHANT_ENVIRONMENTS = exports.verifyWebhook = exports.signWebhook = exports.SIMULATED_FAIRCOIN_OUTCOMES = exports.REQUEST_LOG_RETENTION_DAYS = exports.REQUEST_LOG_METHODS = exports.REFUND_REASONS = exports.RECONCILIATION_MISMATCH_KINDS = exports.PAYOUT_STATUSES = exports.BALANCE_TRANSACTION_TYPES = exports.BALANCE_TRANSACTION_STATUSES = exports.PAYOUT_WEEKLY_ANCHORS = exports.PAYOUT_INTERVALS = exports.PAYMENT_METHOD_CURRENCIES = exports.PAYMENT_METHOD_CONFIGURATION_TYPES = exports.CARD_RAIL_PAYMENT_METHOD_TYPES = void 0;
 // @peable.to/shared-types — public API for the Peable Gateway contract.
 var money_1 = require("./money");
 Object.defineProperty(exports, "UNITS_PER_COIN", { enumerable: true, get: function () { return money_1.UNITS_PER_COIN; } });
@@ -51,8 +51,18 @@ Object.defineProperty(exports, "normalizeDisputeReason", { enumerable: true, get
 var file_1 = require("./file");
 Object.defineProperty(exports, "FILE_PURPOSES", { enumerable: true, get: function () { return file_1.FILE_PURPOSES; } });
 Object.defineProperty(exports, "FILE_PURPOSE_POLICIES", { enumerable: true, get: function () { return file_1.FILE_PURPOSE_POLICIES; } });
+Object.defineProperty(exports, "FILE_UPLOAD_PURPOSES", { enumerable: true, get: function () { return file_1.FILE_UPLOAD_PURPOSES; } });
 Object.defineProperty(exports, "FILE_STATUSES", { enumerable: true, get: function () { return file_1.FILE_STATUSES; } });
 Object.defineProperty(exports, "FILE_TYPES", { enumerable: true, get: function () { return file_1.FILE_TYPES; } });
+var search_1 = require("./search");
+Object.defineProperty(exports, "SEARCHABLE_RESOURCES", { enumerable: true, get: function () { return search_1.SEARCHABLE_RESOURCES; } });
+Object.defineProperty(exports, "SEARCH_QUERY_MAX_CLAUSES", { enumerable: true, get: function () { return search_1.SEARCH_QUERY_MAX_CLAUSES; } });
+Object.defineProperty(exports, "SEARCH_QUERY_MAX_LENGTH", { enumerable: true, get: function () { return search_1.SEARCH_QUERY_MAX_LENGTH; } });
+Object.defineProperty(exports, "SEARCH_SUBSTRING_MIN_LENGTH", { enumerable: true, get: function () { return search_1.SEARCH_SUBSTRING_MIN_LENGTH; } });
+var reporting_1 = require("./reporting");
+Object.defineProperty(exports, "REPORT_RUN_STATUSES", { enumerable: true, get: function () { return reporting_1.REPORT_RUN_STATUSES; } });
+Object.defineProperty(exports, "REPORT_TYPE_IDS", { enumerable: true, get: function () { return reporting_1.REPORT_TYPE_IDS; } });
+Object.defineProperty(exports, "REPORT_TYPE_LAYOUTS", { enumerable: true, get: function () { return reporting_1.REPORT_TYPE_LAYOUTS; } });
 var paymentMethodConfiguration_1 = require("./paymentMethodConfiguration");
 Object.defineProperty(exports, "CARD_RAIL_PAYMENT_METHOD_TYPES", { enumerable: true, get: function () { return paymentMethodConfiguration_1.CARD_RAIL_PAYMENT_METHOD_TYPES; } });
 Object.defineProperty(exports, "PAYMENT_METHOD_CONFIGURATION_TYPES", { enumerable: true, get: function () { return paymentMethodConfiguration_1.PAYMENT_METHOD_CONFIGURATION_TYPES; } });

package/dist/cjs/reporting.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPORT_RUN_STATUSES = exports.REPORT_TYPE_LAYOUTS = 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
+ * changing a report a merchant already parses.
+ */
+exports.REPORT_TYPE_IDS = [
+    'payments.itemized.1',
+    'balance.summary.1',
+    'payouts.itemized.1',
+];
+/**
+ * The layout of each report: its name, every column it can carry and the ones
+ * it carries when `parameters.columns` is absent. Fixed per version.
+ *
+ * - `payments.itemized.1` — one row per payment intent CREATED in the
+ *   interval. Amounts are base-unit strings, as on the API.
+ * - `balance.summary.1` — per currency, the balance at `interval_start`, the
+ *   activity and payouts inside the interval, and the balance at
+ *   `interval_end`, from the ledger (ADR 0015). A figure built on a transaction
+ *   whose fee the provider has not reported is empty, never `0`.
+ * - `payouts.itemized.1` — one row per payout created in the interval.
+ */
+exports.REPORT_TYPE_LAYOUTS = Object.freeze({
+    'payments.itemized.1': {
+        name: 'Itemized payments',
+        columns: [
+            'payment_intent_id',
+            'created_utc',
+            'status',
+            'rail',
+            'currency',
+            'amount',
+            'amount_received',
+            'amount_refunded',
+            'customer_id',
+            'charge_id',
+            'capture_method',
+            'description',
+            'receipt_email',
+            'cancellation_reason',
+            'canceled_at_utc',
+        ],
+        default_columns: [
+            'payment_intent_id',
+            'created_utc',
+            'status',
+            'currency',
+            'amount',
+            'amount_received',
+            'amount_refunded',
+            'customer_id',
+        ],
+        ledger: false,
+    },
+    'balance.summary.1': {
+        name: 'Balance summary',
+        columns: ['category', 'description', 'currency', 'net_amount', 'transaction_count'],
+        default_columns: ['category', 'description', 'currency', 'net_amount'],
+        ledger: true,
+    },
+    'payouts.itemized.1': {
+        name: 'Itemized payouts',
+        columns: [
+            'payout_id',
+            'created_utc',
+            'arrival_date_utc',
+            'status',
+            'currency',
+            'amount',
+            'method',
+            'type',
+            'automatic',
+            'description',
+            'statement_descriptor',
+            'failure_code',
+        ],
+        default_columns: [
+            'payout_id',
+            'created_utc',
+            'arrival_date_utc',
+            'status',
+            'currency',
+            'amount',
+            'automatic',
+        ],
+        ledger: true,
+    },
+});
+exports.REPORT_RUN_STATUSES = ['pending', 'succeeded', 'failed'];

package/dist/cjs/search.js

@@ -0,0 +1,18 @@
+"use strict";
+// The search contract (Stripe's Search API): `GET /v1/<objects>/search?query=…`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEARCH_SUBSTRING_MIN_LENGTH = exports.SEARCH_QUERY_MAX_CLAUSES = exports.SEARCH_QUERY_MAX_LENGTH = exports.SEARCHABLE_RESOURCES = void 0;
+/** Every searchable resource, by its path segment (`/v1/<resource>/search`). */
+exports.SEARCHABLE_RESOURCES = [
+    'payment_intents',
+    'charges',
+    'customers',
+    'products',
+    'prices',
+    'refunds',
+];
+/** Search query bounds — the gateway's, restated so a client can check before it asks. */
+exports.SEARCH_QUERY_MAX_LENGTH = 1000;
+exports.SEARCH_QUERY_MAX_CLAUSES = 10;
+/** A `~` substring needs at least this many characters (Stripe's rule). */
+exports.SEARCH_SUBSTRING_MIN_LENGTH = 3;

package/dist/esm/file.js

@@ -12,9 +12,22 @@ export const FILE_PURPOSES = [
     'business_logo',
     'identity_document',
     'additional_verification',
+    'finance_report_run',
+];
+/**
+ * The purposes a merchant may upload or import. `finance_report_run` is not
+ * among them: a report's CSV is written by Peable's report runs
+ * (`/v1/reporting/report_runs`) and nobody else, so a file of that purpose is
+ * always a report Peable produced.
+ */
+export const FILE_UPLOAD_PURPOSES = [
+    'dispute_evidence',
+    'business_logo',
+    'identity_document',
+    'additional_verification',
 ];
 /** The stored format, by its conventional extension (Stripe's `type`). */
-export const FILE_TYPES = ['pdf', 'png', 'jpg'];
+export const FILE_TYPES = ['pdf', 'png', 'jpg', 'csv'];
 /**
  * Whether the bytes can be used right now.
  *
@@ -26,16 +39,18 @@ export const FILE_TYPES = ['pdf', 'png', 'jpg'];
  */
 export const FILE_STATUSES = ['available', 'withheld', 'removed'];
 /**
- * The upload policy of each purpose: the formats it takes, recognised from the
- * bytes and never from a client's `Content-Type`, and the largest file.
+ * The policy of each purpose: the formats it takes, recognised from the bytes
+ * and never from a client's `Content-Type`, and the largest file.
  *
  * The provider's own ceilings, restated where the upload is parsed, so a file
  * the card network would refuse is refused at upload — not at the one-shot
- * dispute submission it was meant for.
+ * dispute submission it was meant for. `finance_report_run` is Peable's own
+ * output (see {@link FILE_UPLOAD_PURPOSES}); its ceiling bounds a report.
  */
 export const FILE_PURPOSE_POLICIES = Object.freeze({
     dispute_evidence: { types: ['pdf', 'png', 'jpg'], max_bytes: 5 * 1024 * 1024 },
     business_logo: { types: ['png', 'jpg'], max_bytes: 512 * 1024 },
     identity_document: { types: ['pdf', 'png', 'jpg'], max_bytes: 10 * 1024 * 1024 },
     additional_verification: { types: ['pdf', 'png', 'jpg'], max_bytes: 10 * 1024 * 1024 },
+    finance_report_run: { types: ['csv'], max_bytes: 64 * 1024 * 1024 },
 });

package/dist/esm/index.js

@@ -6,7 +6,9 @@ export { PEABLE_API_VERSION, } from './event.js';
 export { WEBHOOK_ENDPOINT_STATUSES, WEBHOOK_ENDPOINT_DISABLED_REASONS, WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT, WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS, } from './webhookEndpoint.js';
 export { PRICE_BILLING_SCHEMES, PRICE_TIERS_MODES, PRICE_TYPES, RECURRING_INTERVALS, RECURRING_USAGE_TYPES, PRICE_TAX_BEHAVIORS, TRANSFORM_QUANTITY_ROUNDS, COUPON_DURATIONS, CATALOG_LIMITS, } from './catalog.js';
 export { DISPUTE_FILE_EVIDENCE_FIELDS, DISPUTE_REASONS, DISPUTE_TEXT_EVIDENCE_FIELDS, normalizeDisputeReason, } from './dispute.js';
-export { FILE_PURPOSES, FILE_PURPOSE_POLICIES, FILE_STATUSES, FILE_TYPES, } from './file.js';
+export { FILE_PURPOSES, FILE_PURPOSE_POLICIES, FILE_UPLOAD_PURPOSES, FILE_STATUSES, FILE_TYPES, } from './file.js';
+export { SEARCHABLE_RESOURCES, SEARCH_QUERY_MAX_CLAUSES, SEARCH_QUERY_MAX_LENGTH, SEARCH_SUBSTRING_MIN_LENGTH, } from './search.js';
+export { REPORT_RUN_STATUSES, REPORT_TYPE_IDS, REPORT_TYPE_LAYOUTS, } from './reporting.js';
 export { CARD_RAIL_PAYMENT_METHOD_TYPES, PAYMENT_METHOD_CONFIGURATION_TYPES, PAYMENT_METHOD_CURRENCIES, } from './paymentMethodConfiguration.js';
 export { PAYOUT_INTERVALS, PAYOUT_WEEKLY_ANCHORS, } from './account.js';
 export { BALANCE_TRANSACTION_STATUSES, BALANCE_TRANSACTION_TYPES, PAYOUT_STATUSES, RECONCILIATION_MISMATCH_KINDS, } from './balance.js';

package/dist/esm/reporting.js

@@ -0,0 +1,89 @@
+/**
+ * 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
+ * changing a report a merchant already parses.
+ */
+export const REPORT_TYPE_IDS = [
+    'payments.itemized.1',
+    'balance.summary.1',
+    'payouts.itemized.1',
+];
+/**
+ * The layout of each report: its name, every column it can carry and the ones
+ * it carries when `parameters.columns` is absent. Fixed per version.
+ *
+ * - `payments.itemized.1` — one row per payment intent CREATED in the
+ *   interval. Amounts are base-unit strings, as on the API.
+ * - `balance.summary.1` — per currency, the balance at `interval_start`, the
+ *   activity and payouts inside the interval, and the balance at
+ *   `interval_end`, from the ledger (ADR 0015). A figure built on a transaction
+ *   whose fee the provider has not reported is empty, never `0`.
+ * - `payouts.itemized.1` — one row per payout created in the interval.
+ */
+export const REPORT_TYPE_LAYOUTS = Object.freeze({
+    'payments.itemized.1': {
+        name: 'Itemized payments',
+        columns: [
+            'payment_intent_id',
+            'created_utc',
+            'status',
+            'rail',
+            'currency',
+            'amount',
+            'amount_received',
+            'amount_refunded',
+            'customer_id',
+            'charge_id',
+            'capture_method',
+            'description',
+            'receipt_email',
+            'cancellation_reason',
+            'canceled_at_utc',
+        ],
+        default_columns: [
+            'payment_intent_id',
+            'created_utc',
+            'status',
+            'currency',
+            'amount',
+            'amount_received',
+            'amount_refunded',
+            'customer_id',
+        ],
+        ledger: false,
+    },
+    'balance.summary.1': {
+        name: 'Balance summary',
+        columns: ['category', 'description', 'currency', 'net_amount', 'transaction_count'],
+        default_columns: ['category', 'description', 'currency', 'net_amount'],
+        ledger: true,
+    },
+    'payouts.itemized.1': {
+        name: 'Itemized payouts',
+        columns: [
+            'payout_id',
+            'created_utc',
+            'arrival_date_utc',
+            'status',
+            'currency',
+            'amount',
+            'method',
+            'type',
+            'automatic',
+            'description',
+            'statement_descriptor',
+            'failure_code',
+        ],
+        default_columns: [
+            'payout_id',
+            'created_utc',
+            'arrival_date_utc',
+            'status',
+            'currency',
+            'amount',
+            'automatic',
+        ],
+        ledger: true,
+    },
+});
+export const REPORT_RUN_STATUSES = ['pending', 'succeeded', 'failed'];

package/dist/esm/search.js

@@ -0,0 +1,15 @@
+// The search contract (Stripe's Search API): `GET /v1/<objects>/search?query=…`.
+/** Every searchable resource, by its path segment (`/v1/<resource>/search`). */
+export const SEARCHABLE_RESOURCES = [
+    'payment_intents',
+    'charges',
+    'customers',
+    'products',
+    'prices',
+    'refunds',
+];
+/** Search query bounds — the gateway's, restated so a client can check before it asks. */
+export const SEARCH_QUERY_MAX_LENGTH = 1000;
+export const SEARCH_QUERY_MAX_CLAUSES = 10;
+/** A `~` substring needs at least this many characters (Stripe's rule). */
+export const SEARCH_SUBSTRING_MIN_LENGTH = 3;

package/dist/types/charge.d.ts

@@ -1,5 +1,6 @@
 import type { CurrencyCode } from './money';
 import type { PaymentIntent } from './paymentIntent';
+import type { BillingDetails } from './paymentMethod';
 /** Card details safe to show: never the number, never the CVC. */
 export interface CardDetails {
     brand: string | null;
@@ -41,6 +42,11 @@ export interface Charge {
     refunded: boolean;
     disputed: boolean;
     outcome: ChargeOutcome | null;
+    /**
+     * Who the card's billing details name, as the provider reported them for this
+     * charge — `null` until the provider snapshot is read (as `outcome`).
+     */
+    billing_details: BillingDetails | null;
     payment_method_details: {
         type: 'card';
         card: CardDetails;

package/dist/types/event.d.ts

@@ -8,6 +8,7 @@ import type { Dispute } from './dispute';
 import type { PaymentIntent } from './paymentIntent';
 import type { PaymentLink } from './paymentLink';
 import type { PaymentMethod } from './paymentMethod';
+import type { ReportRun } from './reporting';
 import type { ConnectedAccount, Refund } from './settlement';
 import type { SetupIntent } from './setupIntent';
 import type { WebhookEndpoint } from './webhookEndpoint';
@@ -140,6 +141,10 @@ export interface WebhookEventPayload {
     'payout.canceled': Payout;
     /** Funds became available in the account; carries the balance read from the ledger. */
     'balance.available': Balance;
+    /** A report run finished: its CSV is `result` (a `finance_report_run` file). */
+    'reporting.report_run.succeeded': ReportRun;
+    /** A report run could not be produced; `error` says why. */
+    'reporting.report_run.failed': ReportRun;
     'billing.observation.updated': BillingObservation;
     /**
      * A synthetic event sent to ONE endpoint when its owner asks to test it

package/dist/types/file.d.ts

@@ -4,10 +4,18 @@
  * reference the file — a `business_logo` is public, a `dispute_evidence` file
  * is private and can only be attached to the merchant's own disputes.
  */
-export declare const FILE_PURPOSES: readonly ["dispute_evidence", "business_logo", "identity_document", "additional_verification"];
+export declare const FILE_PURPOSES: readonly ["dispute_evidence", "business_logo", "identity_document", "additional_verification", "finance_report_run"];
 export type FilePurpose = (typeof FILE_PURPOSES)[number];
+/**
+ * The purposes a merchant may upload or import. `finance_report_run` is not
+ * among them: a report's CSV is written by Peable's report runs
+ * (`/v1/reporting/report_runs`) and nobody else, so a file of that purpose is
+ * always a report Peable produced.
+ */
+export declare const FILE_UPLOAD_PURPOSES: readonly ["dispute_evidence", "business_logo", "identity_document", "additional_verification"];
+export type FileUploadPurpose = (typeof FILE_UPLOAD_PURPOSES)[number];
 /** The stored format, by its conventional extension (Stripe's `type`). */
-export declare const FILE_TYPES: readonly ["pdf", "png", "jpg"];
+export declare const FILE_TYPES: readonly ["pdf", "png", "jpg", "csv"];
 export type FileType = (typeof FILE_TYPES)[number];
 /**
  * Whether the bytes can be used right now.
@@ -21,12 +29,13 @@ export type FileType = (typeof FILE_TYPES)[number];
 export declare const FILE_STATUSES: readonly ["available", "withheld", "removed"];
 export type FileStatus = (typeof FILE_STATUSES)[number];
 /**
- * The upload policy of each purpose: the formats it takes, recognised from the
- * bytes and never from a client's `Content-Type`, and the largest file.
+ * The policy of each purpose: the formats it takes, recognised from the bytes
+ * and never from a client's `Content-Type`, and the largest file.
  *
  * The provider's own ceilings, restated where the upload is parsed, so a file
  * the card network would refuse is refused at upload — not at the one-shot
- * dispute submission it was meant for.
+ * dispute submission it was meant for. `finance_report_run` is Peable's own
+ * output (see {@link FILE_UPLOAD_PURPOSES}); its ceiling bounds a report.
  */
 export declare const FILE_PURPOSE_POLICIES: Readonly<Record<FilePurpose, {
     readonly types: readonly FileType[];
@@ -50,10 +59,16 @@ export interface FileObject {
     type: FileType;
     status: FileStatus;
     /**
-     * A public URL for a `business_logo` that is `available` — what a payer
-     * surface renders. `null` for every other purpose: evidence and identity
-     * documents are never addressable by URL, and their bytes leave Peable only
-     * to the provider they are submitted to.
+     * Where the bytes can be read, while the file is `available`:
+     *
+     *  - a `business_logo`: a PUBLIC URL — what a payer surface renders;
+     *  - a `finance_report_run`: the gateway's `GET /v1/files/:id/contents`,
+     *    which answers the CSV to the merchant's own credential (Stripe's
+     *    `files.stripe.com/v1/files/:id/contents`).
+     *
+     * `null` for every other purpose: evidence and identity documents are never
+     * addressable by URL, and their bytes leave Peable only to the provider they
+     * are submitted to.
      */
     url: string | null;
     created: number;
@@ -68,7 +83,7 @@ export interface FileObject {
  *    checked once, here, and never again.
  */
 export interface CreateFileFromOxyParams {
-    purpose: FilePurpose;
+    purpose: FileUploadPurpose;
     /** Oxy file id. */
     oxy_file: string;
 }

package/dist/types/index.d.ts

@@ -10,7 +10,9 @@ export { PEABLE_API_VERSION, type WebhookEventType, type WebhookEvent, type Webh
 export { WEBHOOK_ENDPOINT_STATUSES, WEBHOOK_ENDPOINT_DISABLED_REASONS, WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT, WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS, type WebhookEnabledEvent, type WebhookEndpoint, type WebhookEndpointStatus, type WebhookEndpointDisabledReason, type DeletedWebhookEndpoint, type CreateWebhookEndpointParams, type UpdateWebhookEndpointParams, type RollWebhookEndpointSecretParams, } from './webhookEndpoint';
 export { PRICE_BILLING_SCHEMES, PRICE_TIERS_MODES, PRICE_TYPES, RECURRING_INTERVALS, RECURRING_USAGE_TYPES, PRICE_TAX_BEHAVIORS, TRANSFORM_QUANTITY_ROUNDS, COUPON_DURATIONS, CATALOG_LIMITS, type PriceBillingScheme, type PriceTiersMode, type PriceType, type RecurringInterval, type RecurringUsageType, type PriceTaxBehavior, type TransformQuantityRound, type CouponDuration, type ProductMarketingFeature, type Product, type DeletedProduct, type PriceTier, type PriceTransformQuantity, type PriceRecurring, type Price, type Coupon, type DeletedCoupon, type PromotionCodeRestrictions, type PromotionCode, type RecurringParams, type PriceTierParams, type PriceDataParams, type DefaultPriceDataParams, type CreateProductParams, type UpdateProductParams, type ProductListParams, type CreatePriceParams, type UpdatePriceParams, type PriceListParams, type CreateCouponParams, type UpdateCouponParams, type CouponListParams, type CreatePromotionCodeParams, type UpdatePromotionCodeParams, type PromotionCodeListParams, } from './catalog';
 export { DISPUTE_FILE_EVIDENCE_FIELDS, DISPUTE_REASONS, DISPUTE_TEXT_EVIDENCE_FIELDS, normalizeDisputeReason, type Dispute, type DisputeEvidence, type DisputeEvidenceDetails, type DisputeEvidenceField, type DisputeEvidenceParams, type DisputeFileEvidenceField, type DisputeReason, type DisputeStatus, type DisputeTextEvidenceField, type ListDisputesParams, type UpdateDisputeParams, } from './dispute';
-export { FILE_PURPOSES, FILE_PURPOSE_POLICIES, FILE_STATUSES, FILE_TYPES, type CreateFileFromOxyParams, type FileObject, type FilePurpose, type FileStatus, type FileType, type ListFilesParams, } from './file';
+export { FILE_PURPOSES, FILE_PURPOSE_POLICIES, FILE_UPLOAD_PURPOSES, FILE_STATUSES, FILE_TYPES, type CreateFileFromOxyParams, type FileObject, type FilePurpose, type FileStatus, type FileType, type FileUploadPurpose, type ListFilesParams, } from './file';
+export { SEARCHABLE_RESOURCES, SEARCH_QUERY_MAX_CLAUSES, SEARCH_QUERY_MAX_LENGTH, SEARCH_SUBSTRING_MIN_LENGTH, type SearchParams, type SearchResult, type SearchableResource, } from './search';
+export { REPORT_RUN_STATUSES, REPORT_TYPE_IDS, REPORT_TYPE_LAYOUTS, type CreateReportRunParams, type ListReportRunsParams, type ReportRun, type ReportRunParameters, type ReportRunStatus, type ReportType, type ReportTypeId, } from './reporting';
 export { CARD_RAIL_PAYMENT_METHOD_TYPES, PAYMENT_METHOD_CONFIGURATION_TYPES, PAYMENT_METHOD_CURRENCIES, type CardRailPaymentMethodType, type CreatePaymentMethodConfigurationParams, type CreatePaymentMethodDomainParams, type ListPaymentMethodDomainsParams, type PaymentMethodConfiguration, type PaymentMethodConfigurationEntry, type PaymentMethodConfigurationEntryParams, type PaymentMethodConfigurationType, type PaymentMethodDisplayPreference, type PaymentMethodDomain, type PaymentMethodDomainWalletStatus, type PaymentMethodUnavailableReason, type UpdatePaymentMethodConfigurationParams, type UpdatePaymentMethodDomainParams, } from './paymentMethodConfiguration';
 export { PAYOUT_INTERVALS, PAYOUT_WEEKLY_ANCHORS, type Account, type AccountBusinessProfile, type AccountCapabilityStatus, type AccountPayoutSchedule, type AccountRequirements, type AccountSettings, type AccountType, type CreateAccountLinkParams, type PayoutInterval, type PayoutWeeklyAnchor, type UpdateAccountParams, } from './account';
 export { BALANCE_TRANSACTION_STATUSES, BALANCE_TRANSACTION_TYPES, PAYOUT_STATUSES, RECONCILIATION_MISMATCH_KINDS, type ApplicationFee, type Balance, type BalanceAmount, type BalanceTransaction, type BalanceTransactionFeeDetail, type BalanceTransactionStatus, type BalanceTransactionType, type CreatePayoutParams, type FeeRefund, type ListBalanceTransactionsParams, type ListPayoutsParams, type Payout, type PayoutReconciliationReport, type PayoutStatus, type ReconciliationMismatch, type ReconciliationMismatchKind, } from './balance';

package/dist/types/reporting.d.ts

@@ -0,0 +1,84 @@
+import type { CurrencyCode } from './money';
+import type { FileObject } from './file';
+/**
+ * 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
+ * changing a report a merchant already parses.
+ */
+export declare const REPORT_TYPE_IDS: readonly ["payments.itemized.1", "balance.summary.1", "payouts.itemized.1"];
+export type ReportTypeId = (typeof REPORT_TYPE_IDS)[number];
+/**
+ * The layout of each report: its name, every column it can carry and the ones
+ * it carries when `parameters.columns` is absent. Fixed per version.
+ *
+ * - `payments.itemized.1` — one row per payment intent CREATED in the
+ *   interval. Amounts are base-unit strings, as on the API.
+ * - `balance.summary.1` — per currency, the balance at `interval_start`, the
+ *   activity and payouts inside the interval, and the balance at
+ *   `interval_end`, from the ledger (ADR 0015). A figure built on a transaction
+ *   whose fee the provider has not reported is empty, never `0`.
+ * - `payouts.itemized.1` — one row per payout created in the interval.
+ */
+export declare const REPORT_TYPE_LAYOUTS: Readonly<Record<ReportTypeId, {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly default_columns: readonly string[];
+    /** Whether the report reads the ledger, and so needs the merchant's account. */
+    readonly ledger: boolean;
+}>>;
+/** `reporting.report_type` — what can be run, and over which interval data exists. */
+export interface ReportType {
+    /** `payments.itemized.1`, … */
+    id: ReportTypeId;
+    object: 'reporting.report_type';
+    livemode: boolean;
+    name: string;
+    /** The column layout's version — the trailing number of the id. */
+    version: number;
+    /** Every column `parameters.columns` may name, in the order they are written. */
+    columns: string[];
+    default_columns: string[];
+    /** The earliest `interval_start` with data (Unix seconds). */
+    data_available_start: number;
+    /** The latest `interval_end` a run may ask for: now — the data is live. */
+    data_available_end: number;
+    /** When the layout last changed. */
+    updated: number;
+}
+export declare const REPORT_RUN_STATUSES: readonly ["pending", "succeeded", "failed"];
+export type ReportRunStatus = (typeof REPORT_RUN_STATUSES)[number];
+/** What a run was asked to cover. */
+export interface ReportRunParameters {
+    /** Inclusive, Unix seconds. */
+    interval_start: number;
+    /** Exclusive, Unix seconds. */
+    interval_end: number;
+    /** The columns, in the layout's order; the report type's `default_columns` when absent. */
+    columns?: string[];
+    /** Only this currency. */
+    currency?: CurrencyCode;
+}
+/** `reporting.report_run` (`frr_…`). */
+export interface ReportRun {
+    id: string;
+    object: 'reporting.report_run';
+    livemode: boolean;
+    created: number;
+    report_type: ReportTypeId;
+    parameters: ReportRunParameters;
+    status: ReportRunStatus;
+    /** Why a `failed` run failed; `null` otherwise. */
+    error: string | null;
+    /** The CSV once `succeeded` — a `file_…` of purpose `finance_report_run`. */
+    result: FileObject | null;
+    succeeded_at: number | null;
+}
+/** `POST /v1/reporting/report_runs`. */
+export interface CreateReportRunParams {
+    report_type: ReportTypeId;
+    parameters: ReportRunParameters;
+}
+/** `GET /v1/reporting/report_runs`. */
+export interface ListReportRunsParams {
+    report_type?: ReportTypeId;
+}

package/dist/types/search.d.ts

@@ -0,0 +1,48 @@
+/**
+ * One page of a search.
+ *
+ * Unlike a {@link List} it pages FORWARD only, by an opaque `next_page` token
+ * passed back as `page`: a search is a filter over the newest-first walk of the
+ * resource, and the token remembers both where the walk stopped and which
+ * query it belongs to (a token used with another query is refused).
+ */
+export interface SearchResult<T> {
+    object: 'search_result';
+    data: T[];
+    has_more: boolean;
+    /** Pass as `page` for the next page; `null` on the last one. */
+    next_page: string | null;
+    /** The path that was searched (`/v1/customers/search`). */
+    url: string;
+    /** Present only when asked for with `expand: ['total_count']`. */
+    total_count?: number;
+}
+/** The parameters every search accepts. */
+export interface SearchParams {
+    /**
+     * The query, in Stripe's search query language:
+     * `email:"jenny@example.com"`, `amount>1000 AND currency:"EUR"`,
+     * `metadata['order_id']:'6735'`, `name~"shirt"`, `-status:"canceled"`,
+     * `customer:null`. Clauses join with spaces or `AND` (all of them must
+     * match) or with `OR` (any), never both; at most 10 clauses and 1000
+     * characters.
+     */
+    query: string;
+    /** 1–100. Default 10. */
+    limit?: number;
+    /** The `next_page` of the previous page, with the SAME query. */
+    page?: string;
+    /**
+     * `data.`-prefixed expansions (`['data.customer']`), and `'total_count'` to
+     * count every match (one extra query).
+     */
+    expand?: string[];
+}
+/** Every searchable resource, by its path segment (`/v1/<resource>/search`). */
+export declare const SEARCHABLE_RESOURCES: readonly ["payment_intents", "charges", "customers", "products", "prices", "refunds"];
+export type SearchableResource = (typeof SEARCHABLE_RESOURCES)[number];
+/** Search query bounds — the gateway's, restated so a client can check before it asks. */
+export declare const SEARCH_QUERY_MAX_LENGTH = 1000;
+export declare const SEARCH_QUERY_MAX_CLAUSES = 10;
+/** A `~` substring needs at least this many characters (Stripe's rule). */
+export declare const SEARCH_SUBSTRING_MIN_LENGTH = 3;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/shared-types",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Shared TypeScript types for the Peable Gateway — the wire contract shared by the backend, SDK, and frontend.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",