@peable.to/contracts 0.4.0 → 1.1.0

package/dist/types/vocabulary/files.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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
+ * 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", "finance_report_run", "tax_document"];
+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", "tax_document"];
+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", "csv"];
+export type FileType = (typeof FILE_TYPES)[number];
+/**
+ * Whether the bytes can be used right now.
+ *
+ *  - `available` — Oxy serves the file; it can be shown or forwarded.
+ *  - `withheld` — the file still exists and is not being served (its owner
+ *    trashed it or made it private); it can come back.
+ *  - `removed` — Oxy said the file is gone for good (deleted, taken down, lost).
+ *    The object stays so whatever referenced it can say why it stopped working.
+ */
+export declare const FILE_STATUSES: readonly ["available", "withheld", "removed"];
+export type FileStatus = (typeof FILE_STATUSES)[number];

package/dist/types/vocabulary/identity.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Peable's own Oxy application: the identity the gateway runs as (`OxyServer`'s
+ * `applicationId`) and the one an Oxy service addresses when it calls the
+ * gateway. One constant, so the gateway's accepted audience and the SDK's
+ * requested one cannot name two different applications.
+ */
+export declare const PEABLE_OXY_APPLICATION_ID = "6a2f851751b784a86fd0e958";
+/** The service-token audience of Peable's gateway (`oxy-service:<application id>`). */
+export declare const PEABLE_SERVICE_AUDIENCE = "oxy-service:6a2f851751b784a86fd0e958";

package/dist/types/vocabulary/index.d.ts

@@ -0,0 +1,19 @@
+export * from './billingPortal';
+export * from './connect';
+export * from './dashboard';
+export * from './catalog';
+export * from './errors';
+export * from './invoices';
+export * from './events';
+export * from './lists';
+export * from './money';
+export * from './tax';
+export * from './subscriptions';
+export * from './reporting';
+export * from './payments';
+export * from './version';
+export * from './checkout';
+export * from './files';
+export * from './identity';
+export * from './merchants';
+export * from './paymentMethodConfigurations';

package/dist/types/vocabulary/invoices.d.ts

@@ -0,0 +1,39 @@
+export declare const INVOICE_STATUSES: readonly ["draft", "open", "paid", "void", "uncollectible"];
+export type InvoiceStatus = (typeof INVOICE_STATUSES)[number];
+/** Why an invoice exists. */
+export declare const INVOICE_BILLING_REASONS: readonly ["manual", "subscription_create", "subscription_cycle", "subscription_update", "subscription_cancel", "upcoming"];
+export type InvoiceBillingReason = (typeof INVOICE_BILLING_REASONS)[number];
+/**
+ * `automatic_tax.status` — Peable Tax (ADR 0011) is computed before an invoice
+ * finalizes (ADR 0018 §2).
+ *
+ *  - `requires_location_inputs` — the customer's location could not be
+ *    established; the invoice cannot finalize until it can.
+ *  - `failed`                   — the calculation failed closed (the provider
+ *    was unavailable, or disagreed with Peable's registrations); retried.
+ *  - `complete`                 — calculated (including `not_registered`,
+ *    which is a calculation that collects zero).
+ */
+export declare const AUTOMATIC_TAX_STATUSES: readonly ["requires_location_inputs", "failed", "complete"];
+export type AutomaticTaxStatus = (typeof AUTOMATIC_TAX_STATUSES)[number];
+/** Where an invoice line comes from: a subscription item's period, or an invoice item. */
+export declare const INVOICE_LINE_TYPES: readonly ["subscription", "invoiceitem"];
+export type InvoiceLineType = (typeof INVOICE_LINE_TYPES)[number];
+/** `pending_invoice_items_behavior` on an invoice create. Default `exclude` (Stripe's). */
+export declare const PENDING_INVOICE_ITEMS_BEHAVIORS: readonly ["include", "exclude"];
+export type PendingInvoiceItemsBehavior = (typeof PENDING_INVOICE_ITEMS_BEHAVIORS)[number];
+export declare const CREDIT_NOTE_STATUSES: readonly ["issued", "void"];
+export type CreditNoteStatus = (typeof CREDIT_NOTE_STATUSES)[number];
+/** `pre_payment` reduces what an open invoice asks for; `post_payment` gives back on a paid one. */
+export declare const CREDIT_NOTE_TYPES: readonly ["pre_payment", "post_payment"];
+export type CreditNoteType = (typeof CREDIT_NOTE_TYPES)[number];
+export declare const CREDIT_NOTE_REASONS: readonly ["duplicate", "fraudulent", "order_change", "product_unsatisfactory"];
+export type CreditNoteReason = (typeof CREDIT_NOTE_REASONS)[number];
+/** A credit note line: part of an invoice line, or a custom amount. */
+export declare const CREDIT_NOTE_LINE_TYPES: readonly ["invoice_line_item", "custom_line_item"];
+export type CreditNoteLineType = (typeof CREDIT_NOTE_LINE_TYPES)[number];
+export declare const CUSTOMER_BALANCE_TRANSACTION_TYPES: readonly ["adjustment", "applied_to_invoice", "credit_note", "invoice_overpaid", "unapplied_from_invoice"];
+export type CustomerBalanceTransactionType = (typeof CUSTOMER_BALANCE_TRANSACTION_TYPES)[number];
+/** The rails a hosted invoice is paid on: a card through the provider's fields, FairCoin from the payer's wallet. */
+export declare const PUBLIC_INVOICE_PAYMENT_METHOD_TYPES: readonly ["card", "faircoin"];
+export type PublicInvoicePaymentMethodType = (typeof PUBLIC_INVOICE_PAYMENT_METHOD_TYPES)[number];

package/dist/types/vocabulary/lists.d.ts

@@ -0,0 +1,9 @@
+export declare const LIST_LIMIT_DEFAULT = 10;
+export declare const LIST_LIMIT_MAX = 100;
+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;
+/** Every searchable resource, by its path segment (`/v1/<resource>/search`). */
+export declare const SEARCHABLE_RESOURCES: readonly ["payment_intents", "charges", "customers", "products", "prices", "refunds", "subscriptions", "invoices"];
+export type SearchableResource = (typeof SEARCHABLE_RESOURCES)[number];

package/dist/types/vocabulary/merchants.d.ts

@@ -0,0 +1,9 @@
+export declare const MERCHANT_ENVIRONMENTS: readonly ["development", "staging", "production"];
+export type MerchantEnvironment = (typeof MERCHANT_ENVIRONMENTS)[number];
+/** The fonts checkout may render in — system stacks only, no remote font is ever loaded. */
+export declare const BRANDING_FONTS: readonly ["system", "inter", "roboto", "open_sans", "lato", "source_sans", "noto_sans", "serif", "monospace"];
+export type BrandingFont = (typeof BRANDING_FONTS)[number];
+export declare const BRANDING_BORDER_STYLES: readonly ["rounded", "rectangular", "pill"];
+export type BrandingBorderStyle = (typeof BRANDING_BORDER_STYLES)[number];
+/** `#rrggbb`, lowercase — the only colour spelling branding stores. */
+export declare const BRANDING_COLOR_PATTERN: RegExp;

package/dist/types/vocabulary/money.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The currencies this gateway can denominate a payment in: FairCoin on the
+ * chain rail, and on the card rail the fiat set the provider settles for the
+ * payment methods Orbit offers (cards, wallets, SEPA Debit, iDEAL, Bancontact,
+ * EPS). A local method narrows it further per payment
+ * (`PAYMENT_METHOD_CURRENCIES` in `paymentMethodConfiguration.ts`).
+ *
+ * A closed set, and the database mirrors it as a CHECK
+ * (`db/schema/valueSets.ts`). ADR 0001 D4: the scale of an amount is a property
+ * of its currency and is NOT implied by the field's type, which is why
+ * {@link CURRENCY_DECIMALS} exists and why {@link UNITS_PER_COIN} must never be
+ * used to interpret a fiat amount.
+ */
+export declare const CURRENCY_CODES: readonly ["FAIR", "EUR", "USD", "GBP", "CHF", "SEK", "NOK", "DKK", "PLN", "CZK", "CAD", "AUD", "JPY"];
+export type CurrencyCode = (typeof CURRENCY_CODES)[number];
+/** Whether an arbitrary string is a currency this gateway knows. */
+export declare function isCurrencyCode(value: string): value is CurrencyCode;
+/**
+ * How many decimal places each currency's smallest unit represents — i.e. an
+ * amount of `1` means `10^-decimals` of one whole unit.
+ *
+ * ISO 4217's minor units for every fiat member (JPY has none). FairCoin's 8 is
+ * a consensus constant and is pinned against {@link UNITS_PER_COIN} by this
+ * package's own tests, so the two spellings of one fact cannot drift.
+ */
+export declare const CURRENCY_DECIMALS: Readonly<Record<CurrencyCode, number>>;
+/** A currency the card rail can denominate a payment in. */
+export type FiatCurrencyCode = Exclude<CurrencyCode, 'FAIR'>;
+/** The fiat members — every currency the card rail can denominate a payment in. */
+export declare const FIAT_CURRENCY_CODES: readonly FiatCurrencyCode[];
+/** The decimal places of `currency`'s smallest unit. */
+export declare function decimalsFor(currency: CurrencyCode): number;
+/**
+ * Frozen FairCoin consensus constant (smallest units per FAIR). Mirrors
+ * `@fairco.in/core`'s branding.ts; inlined to keep this module zero-dependency
+ * for a clean CJS+ESM publish — must stay a bigint, never converted to number.
+ *
+ * FAIRCOIN ONLY. A fiat amount has its own scale (`CURRENCY_DECIMALS`), and
+ * dividing a EUR amount by this constant is off by six orders of magnitude with
+ * nothing failing.
+ */
+export declare const UNITS_PER_COIN = 100000000n;
+/** The spelling of a base-unit amount: digits, no sign, no leading zeros but `0`. */
+export declare const BASE_UNIT_PATTERN: RegExp;
+/** A signed base-unit amount (a customer balance, a balance transaction's net). */
+export declare const SIGNED_BASE_UNIT_PATTERN: RegExp;
+/**
+ * True only for a canonical non-negative integer string in the currency's
+ * smallest unit: one or more decimal digits, no sign, no decimal point, no
+ * leading zeros (except the literal "0"). Floats and negatives are rejected.
+ *
+ * Currency-agnostic on purpose — the pattern is about the SPELLING of an
+ * amount, not its scale, and the same one is restated as a CHECK in the
+ * database (`BASE_UNIT_STRING_PATTERN`), byte-identical.
+ */
+export declare function isBaseUnitString(s: string): boolean;
+/** FairCoin network identifier, mirroring `@fairco.in/core`'s `NetworkType`. */
+export declare const NETWORK_TYPES: readonly ["mainnet", "testnet"];
+export type NetworkType = (typeof NETWORK_TYPES)[number];

package/dist/types/vocabulary/paymentMethodConfigurations.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The methods a configuration can turn on.
+ *
+ * `apple_pay` and `google_pay` are WALLETS over a card: a payment made with one
+ * is a `card` payment, so they appear here and never in a PaymentIntent's
+ * `payment_method_types`. `bizum` is listed because merchants ask for it and the
+ * honest answer is a reason, not an absence: the provider does not offer it.
+ *
+ * Deliberately absent: the provider's own consumer wallet (its brand on Orbit's
+ * checkout, `payment-provider-boundary.md`) and giropay (discontinued by the
+ * scheme).
+ */
+export declare const PAYMENT_METHOD_CONFIGURATION_TYPES: readonly ["card", "apple_pay", "google_pay", "sepa_debit", "ideal", "bancontact", "eps", "bizum"];
+export type PaymentMethodConfigurationType = (typeof PAYMENT_METHOD_CONFIGURATION_TYPES)[number];
+/**
+ * Why a method cannot be offered whatever the merchant chooses.
+ *
+ *  - `provider_unsupported` — the processing provider does not offer it;
+ *  - `requires_card` — a wallet rides on card payments, and card is off.
+ */
+export declare const PAYMENT_METHOD_UNAVAILABLE_REASONS: readonly ["provider_unsupported", "requires_card"];
+export type PaymentMethodUnavailableReason = (typeof PAYMENT_METHOD_UNAVAILABLE_REASONS)[number];

package/dist/types/vocabulary/payments.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Which rail moves the money (ADR 0001 D1). On the INTENT, not on the merchant:
+ * one merchant takes both, and the rail decides which fields mean anything.
+ */
+export declare const PAYMENT_INTENT_RAILS: readonly ["faircoin", "card"];
+export type PaymentIntentRail = (typeof PAYMENT_INTENT_RAILS)[number];
+/**
+ * Stripe's seven statuses, and no others (ADR 0019). The FairCoin rail walks
+ * four of them (`requires_action` → `processing` → `succeeded` | `canceled`); a
+ * card walks all seven. The order is the lifecycle table's
+ * (`@peable.to/shared-types`), which the database CHECK is rendered from.
+ */
+export declare const PAYMENT_INTENT_STATUSES: readonly ["requires_payment_method", "requires_confirmation", "requires_action", "processing", "requires_capture", "succeeded", "canceled"];
+export type PaymentIntentStatus = (typeof PAYMENT_INTENT_STATUSES)[number];
+/**
+ * Why an intent was cancelled — Stripe's reasons, plus `underpaid` (FairCoin
+ * only: a transaction paid less than the amount).
+ */
+export declare const PAYMENT_INTENT_CANCELLATION_REASONS: readonly ["abandoned", "automatic", "duplicate", "fraudulent", "requested_by_customer", "underpaid"];
+export type PaymentIntentCancellationReason = (typeof PAYMENT_INTENT_CANCELLATION_REASONS)[number];
+/** The reasons a MERCHANT may give `POST /v1/payment_intents/:id/cancel`. */
+export declare const MERCHANT_CANCELLATION_REASONS: readonly ["abandoned", "duplicate", "fraudulent", "requested_by_customer"];
+export type MerchantCancellationReason = (typeof MERCHANT_CANCELLATION_REASONS)[number];
+/** When a card is captured: at confirmation, or by `POST …/capture` (card only). */
+export declare const PAYMENT_INTENT_CAPTURE_METHODS: readonly ["automatic", "manual"];
+export type PaymentIntentCaptureMethod = (typeof PAYMENT_INTENT_CAPTURE_METHODS)[number];
+/** Card only: keep the payment method on the customer for later (ADR 0016). */
+export declare const PAYMENT_INTENT_SETUP_FUTURE_USAGES: readonly ["on_session", "off_session"];
+export type PaymentIntentSetupFutureUsage = (typeof PAYMENT_INTENT_SETUP_FUTURE_USAGES)[number];
+/** The card-rail types a PaymentIntent can carry in `payment_method_types`. */
+export declare const CARD_RAIL_PAYMENT_METHOD_TYPES: readonly ["card", "sepa_debit", "ideal", "bancontact", "eps"];
+export type CardRailPaymentMethodType = (typeof CARD_RAIL_PAYMENT_METHOD_TYPES)[number];
+/**
+ * Every payment method type a PaymentIntent can carry: `faircoin` on the chain
+ * rail, the card rail's otherwise. Wallets (Apple Pay, Google Pay) are `card`.
+ */
+export declare const PAYMENT_METHOD_TYPES: readonly ["faircoin", "card", "sepa_debit", "ideal", "bancontact", "eps"];
+export type PaymentMethodType = (typeof PAYMENT_METHOD_TYPES)[number];
+/** The kinds of `last_payment_error` (and a SetupIntent's `last_setup_error`). */
+export declare const PAYMENT_ERROR_TYPES: readonly ["card_error", "payment_error", "api_error"];
+export type PaymentErrorType = (typeof PAYMENT_ERROR_TYPES)[number];
+/** How the payer's client continues: a confirmation credential, or a redirect. */
+export declare const CLIENT_ACTION_KINDS: readonly ["client_secret", "redirect"];
+export type ClientActionKind = (typeof CLIENT_ACTION_KINDS)[number];
+/**
+ * Where one refund stands — the MONEY's own lifecycle, not the payment's.
+ * `canceled` only through `POST /v1/refunds/:id/cancel`.
+ */
+export declare const REFUND_STATUSES: readonly ["pending", "succeeded", "failed", "canceled"];
+export type RefundStatus = (typeof REFUND_STATUSES)[number];
+/** Stripe's refund reasons. */
+export declare const REFUND_REASONS: readonly ["duplicate", "fraudulent", "requested_by_customer"];
+export type RefundReason = (typeof REFUND_REASONS)[number];
+/**
+ * Who created a refund. `provider`: it appeared at the acquirer (a dashboard
+ * refund, a dispute's resolution) and was imported, without an `external_ref`.
+ */
+export declare const REFUND_ORIGINS: readonly ["merchant", "provider"];
+export type RefundOrigin = (typeof REFUND_ORIGINS)[number];
+/** Where a payment's settlement figures stand. `unknown` is not zero. */
+export declare const SETTLEMENT_STATUSES: readonly ["available", "pending", "unknown"];
+export type SettlementStatus = (typeof SETTLEMENT_STATUSES)[number];
+/**
+ * Where a dispute stands. `needs_response` and `under_review` are open; `won`
+ * and `lost` are terminal. There is deliberately no `closed`.
+ */
+export declare const DISPUTE_STATUSES: readonly ["needs_response", "under_review", "won", "lost"];
+export type DisputeStatus = (typeof DISPUTE_STATUSES)[number];
+/** Why the cardholder disputed — Stripe's enum; an unmapped network reason reads `general`. */
+export declare const DISPUTE_REASONS: readonly ["bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "fraudulent", "general", "incorrect_account_details", "insufficient_funds", "noncompliant", "product_not_received", "product_unacceptable", "subscription_canceled", "unrecognized"];
+export type DisputeReason = (typeof DISPUTE_REASONS)[number];
+/**
+ * The TEXT evidence fields — the network's names, never a Peable paraphrase: a
+ * merchant assembling a defence reads their acquirer's guidance, and renamed
+ * fields would make it not apply. The Stripe adapter's name map is a total
+ * `Record` over this set, so a field added here does not compile until it
+ * carries it.
+ */
+export declare const DISPUTE_TEXT_EVIDENCE_FIELDS: readonly ["access_activity_log", "billing_address", "cancellation_policy_disclosure", "cancellation_rebuttal", "customer_email_address", "customer_name", "customer_purchase_ip", "duplicate_charge_explanation", "product_description", "refund_policy_disclosure", "refund_refusal_explanation", "service_date", "shipping_address", "shipping_carrier", "shipping_date", "shipping_tracking_number", "uncategorized_text"];
+export type DisputeTextEvidenceField = (typeof DISPUTE_TEXT_EVIDENCE_FIELDS)[number];
+/** The FILE evidence fields: each names a `file_…` of purpose `dispute_evidence`. */
+export declare const DISPUTE_FILE_EVIDENCE_FIELDS: readonly ["cancellation_policy", "customer_communication", "customer_signature", "duplicate_charge_documentation", "receipt", "refund_policy", "service_documentation", "shipping_documentation", "uncategorized_file"];
+export type DisputeFileEvidenceField = (typeof DISPUTE_FILE_EVIDENCE_FIELDS)[number];
+export type DisputeEvidenceField = DisputeTextEvidenceField | DisputeFileEvidenceField;
+/** The provider's ceiling on one TEXT evidence field, restated where the request is parsed. */
+export declare const DISPUTE_EVIDENCE_TEXT_MAX = 20000;
+export declare const SETUP_INTENT_STATUSES: readonly ["requires_payment_method", "requires_confirmation", "requires_action", "processing", "canceled", "succeeded"];
+export type SetupIntentStatus = (typeof SETUP_INTENT_STATUSES)[number];
+export declare const SETUP_INTENT_USAGES: readonly ["on_session", "off_session"];
+export type SetupIntentUsage = (typeof SETUP_INTENT_USAGES)[number];
+export declare const SETUP_INTENT_CANCELLATION_REASONS: readonly ["abandoned", "duplicate", "requested_by_customer"];
+export type SetupIntentCancellationReason = (typeof SETUP_INTENT_CANCELLATION_REASONS)[number];
+/**
+ * Longest `source.app` of a social payment: an app slug, not a label. The
+ * column CHECK reads the same bound.
+ */
+export declare const SOCIAL_SOURCE_APP_MAX_LENGTH = 32;
+/**
+ * Longest `source.ref` of a social payment. The bound is the whole defence: the
+ * value is opaque, so nothing downstream would notice it growing.
+ */
+export declare const SOCIAL_SOURCE_REF_MAX_LENGTH = 128;
+/** Which side of a social payment the caller was on. */
+export declare const SOCIAL_PAYMENT_DIRECTIONS: readonly ["sent", "received"];
+export type SocialPaymentDirection = (typeof SOCIAL_PAYMENT_DIRECTIONS)[number];
+/** Where a transaction's counterparty identity came from. */
+export declare const ENRICHMENT_KINDS: readonly ["merchant", "user", "unknown"];
+export type EnrichmentKind = (typeof ENRICHMENT_KINDS)[number];
+/** How many addresses one `POST /v1/enrich` resolves (and one social history lists). */
+export declare const ENRICH_MAX_ADDRESSES = 50;
+/**
+ * What `simulate_faircoin_payment` pretends the payer did: `settled` paid the
+ * full amount (`processing` → `succeeded`); `underpaid` sent less
+ * (`processing` → `canceled`, `cancellation_reason: 'underpaid'`).
+ */
+export declare const SIMULATED_FAIRCOIN_OUTCOMES: readonly ["settled", "underpaid"];
+export type SimulatedFaircoinOutcome = (typeof SIMULATED_FAIRCOIN_OUTCOMES)[number];

package/dist/types/vocabulary/reporting.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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. The layouts themselves are
+ * `REPORT_TYPE_LAYOUTS` in `@peable.to/shared-types/reporting`.
+ */
+export declare const REPORT_TYPE_IDS: readonly ["payments.itemized.1", "balance.summary.1", "balance_transactions.itemized.1", "payouts.itemized.1", "refunds.itemized.1", "disputes.itemized.1"];
+export type ReportTypeId = (typeof REPORT_TYPE_IDS)[number];
+export declare const REPORT_RUN_STATUSES: readonly ["pending", "succeeded", "failed"];
+export type ReportRunStatus = (typeof REPORT_RUN_STATUSES)[number];
+/** The HTTP methods a request log records. */
+export declare const REQUEST_LOG_METHODS: readonly ["GET", "POST", "DELETE", "PATCH", "PUT"];
+export type RequestLogMethod = (typeof REQUEST_LOG_METHODS)[number];
+/** A request-log `status` filter's class form (`4xx` is 400–499). */
+export declare const REQUEST_LOG_STATUS_CLASSES: readonly ["2xx", "3xx", "4xx", "5xx"];
+export type RequestLogStatusClass = (typeof REQUEST_LOG_STATUS_CLASSES)[number];
+/** How long a request log is kept (and served). */
+export declare const REQUEST_LOG_RETENTION_DAYS = 30;

package/dist/types/vocabulary/subscriptions.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Where a subscription stands — Stripe's eight.
+ *
+ *  - `incomplete`          — the first invoice is not paid yet; expires to
+ *                            `incomplete_expired` when nobody pays it in time.
+ *  - `incomplete_expired`  — terminal: the first invoice was never paid.
+ *  - `trialing`            — in a trial; nothing is charged until it ends.
+ *  - `active`              — in good standing.
+ *  - `past_due`            — a renewal invoice failed; dunning is retrying it.
+ *  - `unpaid`              — dunning gave up and the merchant's final action
+ *                            is `unpaid`: invoices are still created, access
+ *                            should be withdrawn.
+ *  - `canceled`            — terminal.
+ *  - `paused`              — a trial ended with no payment method and the
+ *                            trial's end behaviour was `pause`; resumed with
+ *                            `POST /v1/subscriptions/:id/resume`.
+ */
+export declare const SUBSCRIPTION_STATUSES: readonly ["incomplete", "incomplete_expired", "trialing", "active", "past_due", "unpaid", "canceled", "paused"];
+export type SubscriptionStatus = (typeof SUBSCRIPTION_STATUSES)[number];
+/** `status=` on a subscription list: a status, `all` (including canceled), or `ended`. */
+export declare const SUBSCRIPTION_LIST_STATUSES: readonly ["incomplete", "incomplete_expired", "trialing", "active", "past_due", "unpaid", "canceled", "paused", "all", "ended"];
+export type SubscriptionListStatus = (typeof SUBSCRIPTION_LIST_STATUSES)[number];
+/** How the subscription's invoices are collected. FairCoin is always `send_invoice`. */
+export declare const COLLECTION_METHODS: readonly ["charge_automatically", "send_invoice"];
+export type CollectionMethod = (typeof COLLECTION_METHODS)[number];
+/** How a change mid-period is billed. */
+export declare const PRORATION_BEHAVIORS: readonly ["create_prorations", "none", "always_invoice"];
+export type ProrationBehavior = (typeof PRORATION_BEHAVIORS)[number];
+/** The proration behaviours a subscription CREATE accepts: there is nothing to invoice at once yet. */
+export declare const CREATE_PRORATION_BEHAVIORS: readonly ["create_prorations", "none"];
+/** What a create does when the first invoice cannot be paid at once. */
+export declare const PAYMENT_BEHAVIORS: readonly ["allow_incomplete", "default_incomplete", "error_if_incomplete"];
+export type PaymentBehavior = (typeof PAYMENT_BEHAVIORS)[number];
+/** What happens to the invoices of a subscription whose collection is paused. */
+export declare const PAUSE_COLLECTION_BEHAVIORS: readonly ["keep_as_draft", "mark_uncollectible", "void"];
+export type PauseCollectionBehavior = (typeof PAUSE_COLLECTION_BEHAVIORS)[number];
+/** What a trial ending with no payment method does (`trial_settings.end_behavior`). */
+export declare const TRIAL_END_BEHAVIORS: readonly ["cancel", "create_invoice", "pause"];
+export type TrialEndBehavior = (typeof TRIAL_END_BEHAVIORS)[number];
+/** Why a subscription was cancelled. */
+export declare const SUBSCRIPTION_CANCELLATION_REASONS: readonly ["cancellation_requested", "payment_failed"];
+export type SubscriptionCancellationReason = (typeof SUBSCRIPTION_CANCELLATION_REASONS)[number];
+/** `billing_cycle_anchor` on a resume: a new period now (the default), or the anchor kept. */
+export declare const RESUME_BILLING_CYCLE_ANCHORS: readonly ["now", "unchanged"];
+export type ResumeBillingCycleAnchor = (typeof RESUME_BILLING_CYCLE_ANCHORS)[number];

package/dist/types/vocabulary/tax.d.ts

@@ -0,0 +1,163 @@
+/**
+ * How a registration lets the seller collect. `standard`/`simplified` cover one
+ * country; the EU One-Stop-Shop schemes cover every EU member state from one
+ * identification state; the US is per state; Canadian PST/QST is per province.
+ */
+export declare const TAX_REGISTRATION_SCHEMES: readonly ["standard", "simplified", "eu_oss_union", "eu_oss_non_union", "us_state_sales_tax", "ca_provincial"];
+export type TaxRegistrationScheme = (typeof TAX_REGISTRATION_SCHEMES)[number];
+/**
+ * Location evidence a jurisdiction accepts. There is deliberately no language,
+ * currency, locale or timezone: none of them is evidence of where a customer
+ * lives, and Peable cannot be told otherwise.
+ */
+export declare const TAX_LOCATION_EVIDENCE_TYPES: readonly ["billing_address", "ip_address", "payment_method_country", "bank_country", "sim_country", "landline_country"];
+export type TaxLocationEvidenceType = (typeof TAX_LOCATION_EVIDENCE_TYPES)[number];
+/** Whether a line's amount includes its tax (`inclusive`) or tax is added on top. */
+export declare const TAX_BEHAVIORS: readonly ["inclusive", "exclusive"];
+export type TaxBehavior = (typeof TAX_BEHAVIORS)[number];
+/** `active` once the owner approved; any edit returns the settings to `draft`. */
+export declare const TAX_SETTINGS_STATUSES: readonly ["draft", "active"];
+export type TaxSettingsStatus = (typeof TAX_SETTINGS_STATUSES)[number];
+/**
+ * Which provider account calculates for a merchant. `platform`: Peable's own
+ * provider account, available only to official Oxy applications, whose seller
+ * is the platform's legal entity. `none`: no provider; sales in a registered
+ * jurisdiction cannot be calculated and fail closed.
+ */
+export declare const TAX_CALCULATION_ACCOUNTS: readonly ["platform", "none"];
+export type TaxCalculationAccount = (typeof TAX_CALCULATION_ACCOUNTS)[number];
+/** `pending_approval` until the owner approves; `scheduled` before `active_from`. */
+export declare const TAX_REGISTRATION_STATUSES: readonly ["pending_approval", "scheduled", "active", "expired"];
+export type TaxRegistrationStatus = (typeof TAX_REGISTRATION_STATUSES)[number];
+/** Only `sufficient` evidence can be calculated against. */
+export declare const TAX_EVIDENCE_STATUSES: readonly ["sufficient", "insufficient", "conflicting"];
+export type TaxLocationEvidenceStatus = (typeof TAX_EVIDENCE_STATUSES)[number];
+/**
+ * Why a calculation's tax is what it is: `collect` (a registration covers the
+ * customer and the provider calculated), `not_registered` (no registration
+ * covers them: zero tax, recorded as such), `nontaxable` (every line used the
+ * nontaxable code).
+ */
+export declare const TAX_COLLECTIONS: readonly ["collect", "not_registered", "nontaxable"];
+export type TaxCollection = (typeof TAX_COLLECTIONS)[number];
+/** A sale, or a refund (or credit note) of one. */
+export declare const TAX_TRANSACTION_TYPES: readonly ["transaction", "reversal"];
+export type TaxTransactionType = (typeof TAX_TRANSACTION_TYPES)[number];
+/**
+ * The product tax codes Peable accepts, starting with digital services and
+ * SaaS — what every Oxy application sells. Ids are Stripe Tax's tax codes, so a
+ * code means the same thing to Peable and to the provider calculating it.
+ * Adding a category is adding a row here; classifying a product is the seller's
+ * decision.
+ */
+export declare const TAX_CODES: readonly [{
+    readonly id: "txcd_00000000";
+    readonly name: "Nontaxable";
+    readonly description: "A product that is not subject to tax anywhere. No tax is calculated.";
+}, {
+    readonly id: "txcd_10000000";
+    readonly name: "General - Electronically Supplied Services";
+    readonly description: "A service delivered electronically over the internet with minimal human involvement.";
+}, {
+    readonly id: "txcd_10103000";
+    readonly name: "Software as a service (SaaS) - personal use";
+    readonly description: "Hosted software accessed online, sold to consumers for personal use.";
+}, {
+    readonly id: "txcd_10103001";
+    readonly name: "Software as a service (SaaS) - business use";
+    readonly description: "Hosted software accessed online, sold to businesses for business use.";
+}, {
+    readonly id: "txcd_10202000";
+    readonly name: "Downloadable Software - personal use";
+    readonly description: "Software downloaded to the customer’s device, for personal use.";
+}, {
+    readonly id: "txcd_10202003";
+    readonly name: "Downloadable Software - business use";
+    readonly description: "Software downloaded to the customer’s device, for business use.";
+}, {
+    readonly id: "txcd_10701100";
+    readonly name: "Website Hosting";
+    readonly description: "Hosting of a website or web application on the seller’s servers.";
+}];
+/** The code of a product that is taxed nowhere. */
+export declare const NONTAXABLE_TAX_CODE = "txcd_00000000";
+/** The code a merchant's settings start with: electronically supplied services. */
+export declare const DEFAULT_TAX_CODE = "txcd_10000000";
+/** Whether `id` is one of {@link TAX_CODES}. */
+export declare function isKnownTaxCode(id: string): boolean;
+/** `unknown` is an answer, not a gap: the owner says they do not know yet. */
+export declare const TAX_LEGAL_ENTITY_TYPES: readonly ["corporation", "limited_liability_company", "partnership", "sole_proprietorship", "nonprofit", "public_body", "other", "unknown"];
+export type TaxLegalEntityType = (typeof TAX_LEGAL_ENTITY_TYPES)[number];
+export declare const TAX_CUSTOMER_TYPES: readonly ["consumers", "businesses", "both", "unknown"];
+export type TaxCustomerType = (typeof TAX_CUSTOMER_TYPES)[number];
+export declare const TAX_SUPPLY_TYPES: readonly ["digital_services", "software_as_a_service", "physical_goods", "professional_services", "other"];
+export type TaxSupplyType = (typeof TAX_SUPPLY_TYPES)[number];
+/**
+ * Where the business ACTUALLY operates. `head_office` and `fixed_establishment`
+ * are the owner's statement of establishment (the EU rule reads them); any
+ * location in a US state is physical presence there.
+ */
+export declare const TAX_OPERATING_LOCATION_KINDS: readonly ["head_office", "fixed_establishment", "office", "warehouse", "employees", "inventory", "other"];
+export type TaxOperatingLocationKind = (typeof TAX_OPERATING_LOCATION_KINDS)[number];
+/**
+ * Where the business stands with a tax authority, IN ITS OWN WORDS.
+ *
+ *  - `unknown` — the owner does not know; an assessment escalates it.
+ *  - `not_registered` — the owner says there is no registration.
+ *  - `application_pending` — an application was made outside Peable and the
+ *    authority has not answered: an ambiguous outcome, never treated as
+ *    registered.
+ *  - `registered` — the owner says the authority registered the business, from
+ *    `effective_from`.
+ *  - `rejected` — the authority refused the application.
+ *  - `ended` — the registration ended at `effective_to`.
+ */
+export declare const TAX_REGISTRATION_DECLARATION_STATUSES: readonly ["unknown", "not_registered", "application_pending", "registered", "rejected", "ended"];
+export type TaxRegistrationDeclarationStatus = (typeof TAX_REGISTRATION_DECLARATION_STATUSES)[number];
+export declare const TAX_FILING_FREQUENCIES: readonly ["monthly", "quarterly", "annual", "unknown"];
+export type TaxFilingFrequency = (typeof TAX_FILING_FREQUENCIES)[number];
+export declare const TAX_DOCUMENT_KINDS: readonly ["registration_certificate", "authority_correspondence", "incorporation_record", "filing_confirmation", "payment_receipt", "other"];
+export type TaxDocumentKind = (typeof TAX_DOCUMENT_KINDS)[number];
+/** `provided`: an available document is attached; `unavailable`: only removed ones are. */
+export declare const TAX_DOCUMENT_CHECKLIST_STATUSES: readonly ["provided", "missing", "unavailable"];
+export type TaxDocumentChecklistStatus = (typeof TAX_DOCUMENT_CHECKLIST_STATUSES)[number];
+/** The tax a jurisdiction rule is about. */
+export declare const TAX_TYPES: readonly ["vat", "sales_tax"];
+export type TaxType = (typeof TAX_TYPES)[number];
+/** The window a rule's threshold is measured over. */
+export declare const TAX_THRESHOLD_PERIODS: readonly ["current_or_previous_calendar_year", "preceding_twelve_calendar_months"];
+export type TaxThresholdPeriod = (typeof TAX_THRESHOLD_PERIODS)[number];
+/** Whether a tax professional has signed a rule off. */
+export declare const TAX_RULE_REVIEW_STATUSES: readonly ["unreviewed", "reviewed"];
+export type TaxRuleReviewStatus = (typeof TAX_RULE_REVIEW_STATUSES)[number];
+/**
+ * What an assessment found for one jurisdiction.
+ *
+ *  - `registration_declared` — the owner declares a registration in force.
+ *  - `likely_required` — the rule indicates an obligation; a person decides.
+ *  - `approaching_threshold` — at or above 80% of the threshold.
+ *  - `not_indicated` — nothing in the recorded facts indicates one.
+ *  - `uncertain` — the facts are missing or contradictory; escalated.
+ *  - `unsupported` — sales exist where no supported rule applies.
+ */
+export declare const TAX_OBLIGATION_OUTCOMES: readonly ["registration_declared", "likely_required", "approaching_threshold", "not_indicated", "uncertain", "unsupported"];
+export type TaxObligationOutcome = (typeof TAX_OBLIGATION_OUTCOMES)[number];
+export declare const TAX_REVIEW_ITEM_STATUSES: readonly ["open", "resolved", "dismissed"];
+export type TaxReviewItemStatus = (typeof TAX_REVIEW_ITEM_STATUSES)[number];
+export declare const TAX_REVIEW_SEVERITIES: readonly ["action_required", "review"];
+export type TaxReviewSeverity = (typeof TAX_REVIEW_SEVERITIES)[number];
+/** What the owner decided. None of them activates collection. */
+export declare const TAX_REVIEW_DECISIONS: readonly ["will_register", "registered_outside_peable", "not_required", "accepted_risk", "facts_corrected", "dismissed"];
+export type TaxReviewDecision = (typeof TAX_REVIEW_DECISIONS)[number];
+/** Who recorded a compliance change: the owner, a service credential, or Peable itself. */
+export declare const TAX_ACTOR_TYPES: readonly ["user", "service", "system"];
+export type TaxActorType = (typeof TAX_ACTOR_TYPES)[number];
+export declare const TAX_DEADLINE_KINDS: readonly ["return", "payment", "registration"];
+export type TaxDeadlineKind = (typeof TAX_DEADLINE_KINDS)[number];
+export declare const TAX_DEADLINE_STATUSES: readonly ["upcoming", "due_soon", "passed"];
+export type TaxDeadlineStatus = (typeof TAX_DEADLINE_STATUSES)[number];
+export declare const TAX_COMPLIANCE_CAPABILITY_STATUSES: readonly ["available", "limited", "not_available", "out_of_scope"];
+export type TaxComplianceCapabilityStatus = (typeof TAX_COMPLIANCE_CAPABILITY_STATUSES)[number];
+/** VAT/sales tax, corporate income tax and annual company filings are different obligations. */
+export declare const TAX_COMPLIANCE_CAPABILITY_CATEGORIES: readonly ["vat_sales_tax", "corporate_income_tax", "annual_company_filings", "workflow"];
+export type TaxComplianceCapabilityCategory = (typeof TAX_COMPLIANCE_CAPABILITY_CATEGORIES)[number];

package/dist/types/vocabulary/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The date of the one wire (ADR 0014 D2): echoed as `Peable-Version` on every
+ * response, the `api_version` every event is stored under, and the only value
+ * a caller may send in `Peable-Version`. One constant, so the header, the
+ * stored events and the SDK's `apiVersion` cannot name two different wires.
+ */
+export declare const PEABLE_API_VERSION = "2026-11-03";
+/** Every wire date the gateway serves. Dated versions side by side are a later decision (ADR 0014 D2). */
+export declare const PEABLE_API_VERSIONS: readonly ["2026-11-03"];
+export type PeableApiVersion = (typeof PEABLE_API_VERSIONS)[number];