@peable.to/shared-types 0.14.0 → 0.16.0

package/dist/types/paymentLink.d.ts

@@ -1,72 +1,177 @@
 import type { ContributionDetails } from '@peable.to/contracts';
+import type { CheckoutBranding } from './branding';
+import type { CheckoutAdjustableQuantity, CheckoutAfterCompletion, CheckoutBillingAddressCollection, CheckoutCustomField, CheckoutCustomFieldParams, CheckoutCustomerCreation, CheckoutLineItem, CheckoutLocale, CheckoutSubmitType } from './checkoutSession';
 import type { CurrencyCode } from './money';
-import type { NetworkType } from './network';
 import type { MerchantDisplay } from './merchantDisplay';
+import type { NetworkType } from './network';
 import type { PaymentIntentRail } from './paymentIntent';
-/** The merchant-facing DTO — returned by the merchant-authed CRUD routes. */
+export declare const PAYMENT_LINK_LIMITS: Readonly<{
+    lineItemsMax: 20;
+    customMessageMax: 500;
+}>;
 export interface PaymentLink {
     id: string;
     object: 'payment_link';
-    /**
-     * Which of the provider's two worlds this object belongs to (ADR 0017):
-     * `true` for a `production` merchant, `false` for every other environment.
-     */
     livemode: boolean;
-    contribution?: ContributionDetails;
-    /**
-     * Amount in the currency's smallest unit, as a canonical integer string.
-     * Never a float, and never interpretable without `currency`.
-     */
-    amount: string;
+    active: boolean;
     currency: CurrencyCode;
     rail: PaymentIntentRail;
-    /** FairCoin rail only; `null` on a card link. */
     network: NetworkType | null;
-    active: boolean;
+    /** The link's prices (`GET /v1/payment_links/:id/line_items` lists them in full). */
+    line_items: CheckoutLineItem[];
+    allow_promotion_codes: boolean;
+    billing_address_collection: CheckoutBillingAddressCollection;
+    shipping_address_collection: {
+        allowed_countries: string[];
+    } | null;
+    phone_number_collection: {
+        enabled: boolean;
+    };
+    tax_id_collection: {
+        enabled: boolean;
+    };
+    custom_fields: CheckoutCustomField[];
+    consent_collection: {
+        terms_of_service: 'none' | 'required';
+    } | null;
+    automatic_tax: {
+        enabled: boolean;
+    };
+    customer_creation: CheckoutCustomerCreation;
+    after_completion: CheckoutAfterCompletion;
+    restrictions: {
+        completed_sessions: {
+            limit: number;
+            count: number;
+        };
+    } | null;
+    submit_type: CheckoutSubmitType;
+    locale: CheckoutLocale | null;
+    /** Present on an organization contribution link (FairCoin). */
+    contribution?: ContributionDetails;
     metadata: Record<string, string>;
-    /** Optional post-payment redirect target for the checkout page. */
-    success_url?: string;
-    /** Canonical `checkout.peable.to/l/<id>` URL. */
+    /** `checkout.peable.to/l/<id>` — share it, or render it as a QR code. */
     url: string;
     created: number;
     updated_at: number;
 }
-/** What an unauthenticated checkout-page visitor may see — no secrets, no metadata. */
+/** What an anonymous visitor may see before checkout starts — no metadata, no counts. */
 export interface PublicPaymentLink {
     id: string;
     object: 'payment_link';
-    /**
-     * Which of the provider's two worlds this object belongs to (ADR 0017):
-     * `true` for a `production` merchant, `false` for every other environment.
-     */
     livemode: boolean;
-    contribution?: ContributionDetails;
-    amount: string;
+    active: boolean;
     currency: CurrencyCode;
     rail: PaymentIntentRail;
     network: NetworkType | null;
-    active: boolean;
+    line_items: CheckoutLineItem[];
+    contribution?: ContributionDetails;
+    /** A fixed contribution's amount; `null` when the payer chooses (or for a price link). */
+    contribution_amount: string | null;
     merchant: MerchantDisplay;
+    branding: CheckoutBranding;
+    locale: CheckoutLocale | null;
+}
+export interface PaymentLinkLineItemParams {
+    price: string;
+    quantity: number;
+    adjustable_quantity?: {
+        enabled: boolean;
+        minimum?: number;
+        maximum?: number;
+    };
+}
+export interface PaymentLinkAfterCompletionParams {
+    type: 'redirect' | 'hosted_confirmation';
+    /** `type: redirect` — may carry `{CHECKOUT_SESSION_ID}`. */
+    redirect?: {
+        url: string;
+    };
+    hosted_confirmation?: {
+        custom_message?: string;
+    };
 }
 export interface CreatePaymentLinkParams {
-    amount: string;
-    /** Defaults to `'faircoin'`, so pre-ADR-0001 integrations keep working. */
-    rail?: PaymentIntentRail;
-    /** Required on the faircoin rail; refused on the card rail. */
-    network?: NetworkType;
-    /** Defaults to `'FAIR'` on the faircoin rail; required on the card rail. */
-    currency?: CurrencyCode;
+    /** 1–20 prices of ONE currency, one-time prices only. */
+    line_items: PaymentLinkLineItemParams[];
+    allow_promotion_codes?: boolean;
+    billing_address_collection?: CheckoutBillingAddressCollection;
+    shipping_address_collection?: {
+        allowed_countries: string[];
+    };
+    phone_number_collection?: {
+        enabled: boolean;
+    };
+    tax_id_collection?: {
+        enabled: boolean;
+    };
+    custom_fields?: CheckoutCustomFieldParams[];
+    consent_collection?: {
+        terms_of_service?: 'none' | 'required';
+    };
+    automatic_tax?: {
+        enabled: boolean;
+    };
+    customer_creation?: CheckoutCustomerCreation;
+    after_completion?: PaymentLinkAfterCompletionParams;
+    restrictions?: {
+        completed_sessions: {
+            limit: number;
+        };
+    };
+    submit_type?: CheckoutSubmitType;
+    locale?: CheckoutLocale | 'auto';
     metadata?: Record<string, string>;
-    success_url?: string;
 }
 /**
- * `POST /v1/payment_links/:id`. `amount`/`network` are deliberately absent — a
- * link's price is immutable once shared.
+ * `POST /v1/payment_links/:id`. The line items are fixed once shared (a payer
+ * may hold a session priced from them); everything else may change.
  */
 export interface UpdatePaymentLinkParams {
     active?: boolean;
+    allow_promotion_codes?: boolean;
+    billing_address_collection?: CheckoutBillingAddressCollection;
+    shipping_address_collection?: {
+        allowed_countries: string[];
+    } | '';
+    phone_number_collection?: {
+        enabled: boolean;
+    };
+    tax_id_collection?: {
+        enabled: boolean;
+    };
+    custom_fields?: CheckoutCustomFieldParams[] | '';
+    consent_collection?: {
+        terms_of_service?: 'none' | 'required';
+    };
+    automatic_tax?: {
+        enabled: boolean;
+    };
+    customer_creation?: CheckoutCustomerCreation;
+    after_completion?: PaymentLinkAfterCompletionParams;
+    restrictions?: {
+        completed_sessions: {
+            limit: number;
+        };
+    } | '';
+    submit_type?: CheckoutSubmitType;
+    locale?: CheckoutLocale | 'auto';
     /** A patch: named keys are set, `""` removes a key, others are kept. */
     metadata?: Record<string, string>;
-    /** `null` removes it. */
-    success_url?: string | null;
 }
+/**
+ * `POST /v1/payment_links/:id/checkout_sessions` — a payer starting checkout
+ * (anonymous, rate-limited). A contribution link the payer prices takes
+ * `amount`; nothing else is the payer's to say.
+ */
+export interface CreatePaymentLinkSessionParams {
+    amount?: string;
+}
+/** Its answer: where to go — the hosted session and the secret that opens it. */
+export interface PaymentLinkSessionStart {
+    object: 'checkout_session_start';
+    id: string;
+    client_secret: string;
+    url: string;
+}
+export type { CheckoutAdjustableQuantity };

package/dist/types/settlement.d.ts

@@ -1,3 +1,4 @@
+import type { AccountRequirements } from './account';
 import type { CurrencyCode } from './money';
 import type { NetworkType } from './network';
 import type { PaymentIntent } from './paymentIntent';
@@ -84,17 +85,12 @@ export interface ConnectedAccount {
     transfers_capability: CapabilityStatus | null;
     card_payments_capability: CapabilityStatus | null;
     /**
-     * COUNTS of outstanding requirements, never the requirements themselves and
-     * never their values. The gateway records that a seller owes a document; it
-     * does not learn what the document says.
+     * What the provider is waiting on — requirement IDENTIFIERS, never their
+     * values (the gateway records that a seller owes a document; it never learns
+     * what the document says) — and the provider's own `disabled_reason`. The
+     * same shape as `Account.requirements`.
      */
-    requirements: {
-        currently_due: number;
-        eventually_due: number;
-        past_due: number;
-        pending_verification: number;
-    };
-    disabled_reason_codes: readonly string[];
+    requirements: AccountRequirements;
     last_synced_at: number | null;
     created: number;
     updated_at: number;
@@ -203,8 +199,15 @@ export interface Settlement {
     /** Present only when a conversion happened. `null` is not a rate of 1. */
     exchange_rate: number | null;
 }
-/** Where one refund stands — the MONEY's own lifecycle, not the payment's. */
-export type RefundStatus = 'pending' | 'succeeded' | 'failed';
+/**
+ * Where one refund stands — the MONEY's own lifecycle, not the payment's.
+ * `canceled` only through `POST /v1/refunds/:id/cancel`, where the provider
+ * still allows it.
+ */
+export type RefundStatus = 'pending' | 'succeeded' | 'failed' | 'canceled';
+/** 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.
  *
@@ -229,7 +232,31 @@ export interface Refund {
     amount: string;
     currency: CurrencyCode | string;
     status: RefundStatus;
+    reason: RefundReason | null;
     failure_code: string | null;
+    metadata: Record<string, string>;
     created: number;
     updated_at: number;
 }
+/** `POST /v1/refunds`. */
+export interface CreateRefundParams {
+    /** The `pi_…` being refunded. */
+    payment_intent: string;
+    /** YOUR id for this refund. The idempotency. */
+    external_ref: string;
+    /** Minor units, as a canonical integer string. Zero is refused. */
+    amount: string;
+    reason?: RefundReason;
+    metadata?: Record<string, string>;
+    /**
+     * Also refund Orbit's application fee, in proportion to the amount refunded
+     * (a payment that carried one: a destination charge, ADR 0015 §2).
+     */
+    refund_application_fee?: boolean;
+    /** Also reverse the transfer to the destination account, in proportion. */
+    reverse_transfer?: boolean;
+}
+/** `POST /v1/refunds/:id` — the merchant's own bookkeeping; `metadata` is a patch. */
+export interface UpdateRefundParams {
+    metadata?: Record<string, string>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/shared-types",
-  "version": "0.14.0",
+  "version": "0.16.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",