@peable.to/contracts 0.4.0 → 1.0.0

package/dist/esm/resources/payments/charges.js

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+import { listOf, searchResultOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject, expandable } from '../../common/objects.js';
+import { expandOnlyQuery, idParam, listQuery, searchQuery } from '../../common/params.js';
+import { amount, currency, livemode, metadata, nullableString, unixSeconds, } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { billingDetailsSchema, cardDetailsSchema } from '../core/paymentMethods.js';
+/**
+ * Charges (`ch_…`) — the read-only record of the money a CARD PaymentIntent
+ * moved (ADR 0019). Peable's object over the provider's charge, which stays an
+ * internal binding (ADR 0016). A FairCoin payment has no charge: its chain side
+ * is `PaymentIntent.faircoin`.
+ */
+export const chargeOutcomeSchema = defineComponent('ChargeOutcome', z
+    .object({
+    network_status: nullableString.describe('`approved_by_network`, `declined_by_network`, `not_sent_to_network`, `reversed_after_approval`.'),
+    risk_level: nullableString.describe('`normal`, `elevated`, `highest`, or `not_assessed`.'),
+    type: nullableString.describe('`authorized`, `manual_review`, `issuer_declined`, `blocked`, `invalid`.'),
+    seller_message: nullableString.describe("Peable's own one-line explanation for the merchant — never the provider's prose."),
+})
+    .strict());
+export const chargeSchema = defineObject('charge', 'Charge', z
+    .object({
+    id: z.string(),
+    object: z.literal('charge'),
+    livemode,
+    payment_intent: expandable('payment_intent', '`pi_…`, or the PaymentIntent with `expand[]=payment_intent`.'),
+    customer: expandable('customer', '`cus_…`, or the Customer with `expand[]=customer`.').nullable(),
+    payment_method: expandable('payment_method', '`pm_…`, or the PaymentMethod with `expand[]=payment_method`.').nullable(),
+    amount,
+    amount_captured: amount,
+    amount_refunded: amount,
+    currency,
+    status: z
+        .literal('succeeded')
+        .describe('Always `succeeded`: Peable records the authorization that succeeded.'),
+    paid: z.boolean(),
+    captured: z.boolean(),
+    refunded: z
+        .boolean()
+        .describe('All of it came back — by refunds, or by releasing an uncaptured authorization.'),
+    disputed: z.boolean(),
+    outcome: chargeOutcomeSchema.nullable(),
+    billing_details: billingDetailsSchema
+        .nullable()
+        .describe("Who the card's billing details name, as the provider reported them; `null` until the provider snapshot is read."),
+    payment_method_details: z
+        .object({ type: z.literal('card'), card: cardDetailsSchema })
+        .strict()
+        .nullable(),
+    receipt_url: nullableString.describe("The provider's own URL never reaches the wire."),
+    balance_transaction: nullableString.describe("The ledger's `txn_…` once the provider's balance transaction was ingested (ADR 0015 §4); never a guess."),
+    application_fee: nullableString.describe("Orbit's `fee_…` taken on this charge, once the provider created it."),
+    application_fee_amount: amount
+        .nullable()
+        .describe('The fee instructed on the payment (`application_fee_amount`).'),
+    description: nullableString,
+    receipt_email: nullableString,
+    metadata,
+    created: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'ch_0193b8f2c1a87d3e9f4a',
+            object: 'charge',
+            livemode: false,
+            payment_intent: 'pi_0193b8f2c1a87d3e9f4a',
+            customer: 'cus_0193b8f2c1a87d3e9f4a',
+            payment_method: 'pm_0193b8f2c1a87d3e9f4a',
+            amount: '2500',
+            amount_captured: '2500',
+            amount_refunded: '0',
+            currency: 'EUR',
+            status: 'succeeded',
+            paid: true,
+            captured: true,
+            refunded: false,
+            disputed: false,
+            outcome: {
+                network_status: 'approved_by_network',
+                risk_level: 'normal',
+                type: 'authorized',
+                seller_message: 'Payment complete.',
+            },
+            billing_details: null,
+            payment_method_details: {
+                type: 'card',
+                card: {
+                    brand: 'visa',
+                    last4: '4242',
+                    exp_month: 12,
+                    exp_year: 2030,
+                    country: 'US',
+                    funding: 'credit',
+                },
+            },
+            receipt_url: null,
+            balance_transaction: null,
+            application_fee: null,
+            application_fee_amount: null,
+            description: null,
+            receipt_email: null,
+            metadata: {},
+            created: 1793750400,
+        },
+    ],
+});
+export const listChargesQuery = listQuery({
+    payment_intent: idParam.optional().describe("Only this payment's charges (`pi_…`)."),
+});
+export const chargeRoutes = [
+    defineRoute({
+        operationId: 'listCharges',
+        method: 'get',
+        path: '/v1/charges',
+        tag: 'Charges',
+        summary: 'List charges',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listChargesQuery,
+        response: listOf(chargeSchema),
+        sdk: 'charges.list',
+        expandable: 'charge',
+    }),
+    defineRoute({
+        operationId: 'retrieveCharge',
+        method: 'get',
+        path: '/v1/charges/{id}',
+        tag: 'Charges',
+        summary: 'Retrieve a charge',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The charge (`ch_…`).' },
+        query: expandOnlyQuery,
+        response: chargeSchema,
+        sdk: 'charges.retrieve',
+        expandable: 'charge',
+    }),
+    defineRoute({
+        operationId: 'searchCharges',
+        method: 'get',
+        path: '/v1/charges/search',
+        tag: 'Charges',
+        summary: 'Search charges',
+        description: "Stripe's query language over `amount`, `currency`, `customer`, `payment_intent`, `status`, `captured`, `refunded`, `disputed`, `created` and `metadata['key']`.",
+        auth: 'service',
+        scope: 'payments:read',
+        query: searchQuery,
+        response: searchResultOf(chargeSchema),
+        sdk: 'charges.search',
+        expandable: 'charge',
+    }),
+];

package/dist/esm/resources/payments/disputes.js

@@ -0,0 +1,201 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject, expandable } from '../../common/objects.js';
+import { expandOnlyQuery, idParam, listQuery, metadataUpdateParam } from '../../common/params.js';
+import { amount, currency, livemode, metadata, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { DISPUTE_EVIDENCE_TEXT_MAX, DISPUTE_FILE_EVIDENCE_FIELDS, DISPUTE_REASONS, DISPUTE_STATUSES, DISPUTE_TEXT_EVIDENCE_FIELDS, } from '../../vocabulary/payments.js';
+/**
+ * Disputes (`dp_…`) — the card network holding a payment's money while a
+ * cardholder contests it. A dispute is a DEADLINE: `evidence_details.due_by`
+ * arrives with it. The network's own dispute id never appears.
+ */
+/** Every evidence field, `null` when unset. */
+const evidenceFields = (field) => Object.fromEntries([...DISPUTE_TEXT_EVIDENCE_FIELDS, ...DISPUTE_FILE_EVIDENCE_FIELDS].map((name) => [name, field]));
+/**
+ * A merchant's evidence as the dispute holds it. Present ONLY on a live read
+ * (`GET /v1/disputes/{id}` and the answers of its update and close): the text
+ * is read from the provider, where a draft lives (Peable keeps none of its
+ * words); the file half is the `file_…` ids attached. Lists and events never
+ * carry it.
+ */
+export const disputeEvidenceSchema = defineComponent('DisputeEvidence', z.object(evidenceFields(z.string().nullable())).strict());
+export const disputeEvidenceDetailsSchema = defineComponent('DisputeEvidenceDetails', z
+    .object({
+    due_by: unixSeconds
+        .nullable()
+        .describe('When the network stops accepting evidence; `null` once the dispute is closed.'),
+    has_evidence: z.boolean().describe('Whether any evidence has been staged or submitted.'),
+    past_due: z.boolean().describe('Whether the deadline passed without a submission.'),
+    submission_count: z
+        .number()
+        .int()
+        .min(0)
+        .max(1)
+        .describe('`0` or `1`: a response is one-shot at the network.'),
+    submitted_at: unixSeconds
+        .nullable()
+        .describe('When the response reached the network; `null` while it has not.'),
+})
+    .strict());
+export const disputeSchema = defineObject('dispute', 'Dispute', z
+    .object({
+    id: z.string(),
+    object: z.literal('dispute'),
+    livemode,
+    amount: amount.describe("The DISPUTED amount, which may be less than the payment's: a cardholder can contest part of a charge."),
+    currency,
+    charge: expandable('charge', '`ch_…`, or the Charge with `expand[]=charge`.').nullable(),
+    payment_intent: expandable('payment_intent', 'The disputed payment (`pi_…`), or the PaymentIntent with `expand[]=payment_intent`.'),
+    status: z
+        .enum(DISPUTE_STATUSES)
+        .describe('`needs_response` and `under_review` are open; `won` and `lost` are terminal and say where the money ended up.'),
+    reason: z.enum(DISPUTE_REASONS),
+    is_charge_refundable: z
+        .boolean()
+        .describe('Whether the disputed payment can still be refunded.'),
+    evidence_details: disputeEvidenceDetailsSchema,
+    evidence: disputeEvidenceSchema
+        .optional()
+        .describe('Live reads only: never on a list or an event.'),
+    metadata,
+    created: unixSeconds,
+    updated_at: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'dp_0193b8f2c1a87d3e9f4a',
+            object: 'dispute',
+            livemode: false,
+            amount: '2500',
+            currency: 'EUR',
+            charge: 'ch_0193b8f2c1a87d3e9f4a',
+            payment_intent: 'pi_0193b8f2c1a87d3e9f4a',
+            status: 'needs_response',
+            reason: 'product_not_received',
+            is_charge_refundable: true,
+            evidence_details: {
+                due_by: 1794355200,
+                has_evidence: false,
+                past_due: false,
+                submission_count: 0,
+                submitted_at: null,
+            },
+            metadata: {},
+            created: 1793750400,
+            updated_at: 1793750400,
+        },
+    ],
+});
+const FILE_ID_MAX = 255;
+/** `""` unsets a field, as on Stripe. */
+const textEvidence = z.string().max(DISPUTE_EVIDENCE_TEXT_MAX).optional();
+const fileEvidence = z.string().max(FILE_ID_MAX).optional();
+/**
+ * The evidence fields, in the network's names — a CLOSED set. Unknown keys are
+ * REFUSED rather than dropped: a merchant who sent `tracking_number` instead of
+ * `shipping_tracking_number` would otherwise submit, finally, a response
+ * missing the field they relied on.
+ */
+export const disputeEvidenceParams = z
+    .object({
+    ...Object.fromEntries(DISPUTE_TEXT_EVIDENCE_FIELDS.map((field) => [field, textEvidence])),
+    ...Object.fromEntries(DISPUTE_FILE_EVIDENCE_FIELDS.map((field) => [field, fileEvidence])),
+})
+    .strict()
+    .describe('Any subset of the fields: a text field is your words (at most 20,000 characters), a file field a `file_…` of purpose `dispute_evidence`. `""` unsets a field.');
+/**
+ * `submit: false` (the default) STAGES the evidence: text goes to the provider
+ * as a draft, files are attached by id. `submit: true` uploads the attached
+ * files and submits everything — ONCE; a second submission is refused.
+ */
+export const updateDisputeParams = z
+    .object({
+    evidence: disputeEvidenceParams.optional(),
+    metadata: metadataUpdateParam.optional(),
+    submit: z.boolean().optional(),
+})
+    .strict();
+export const closeDisputeParams = z.object({}).strict();
+export const listDisputesQuery = listQuery({
+    payment_intent: idParam.optional().describe("Only this payment's disputes (`pi_…`)."),
+    charge: idParam.optional().describe("Only this charge's disputes (`ch_…`)."),
+});
+/** The per-payment sub-list: the payment is in the path. */
+export const listPaymentIntentDisputesQuery = listQuery({});
+const disputeId = { disputeId: 'The dispute (`dp_…`).' };
+export const disputeRoutes = [
+    defineRoute({
+        operationId: 'listPaymentIntentDisputes',
+        method: 'get',
+        path: '/v1/payment_intents/{intentId}/disputes',
+        tag: 'Disputes',
+        summary: "List a payment's disputes",
+        auth: 'service',
+        scope: 'payments:read',
+        params: { intentId: 'The payment intent (`pi_…`).' },
+        query: listPaymentIntentDisputesQuery,
+        response: listOf(disputeSchema),
+        sdk: 'disputes.listForPaymentIntent',
+        expandable: 'dispute',
+    }),
+    defineRoute({
+        operationId: 'listDisputes',
+        method: 'get',
+        path: '/v1/disputes',
+        tag: 'Disputes',
+        summary: 'List disputes',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listDisputesQuery,
+        response: listOf(disputeSchema),
+        sdk: 'disputes.list',
+        expandable: 'dispute',
+    }),
+    defineRoute({
+        operationId: 'retrieveDispute',
+        method: 'get',
+        path: '/v1/disputes/{disputeId}',
+        tag: 'Disputes',
+        summary: 'Retrieve a dispute',
+        description: 'The one read that carries `evidence`, read live from the provider.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: disputeId,
+        query: expandOnlyQuery,
+        response: disputeSchema,
+        sdk: 'disputes.retrieve',
+        expandable: 'dispute',
+    }),
+    defineRoute({
+        operationId: 'updateDispute',
+        method: 'post',
+        path: '/v1/disputes/{disputeId}',
+        tag: 'Disputes',
+        summary: 'Update a dispute',
+        description: 'Metadata, a staged draft of evidence, or — with `submit: true` — the one submission. A dispute that no longer takes evidence answers 409.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: disputeId,
+        body: updateDisputeParams,
+        response: disputeSchema,
+        sdk: 'disputes.update',
+    }),
+    defineRoute({
+        operationId: 'closeDispute',
+        method: 'post',
+        path: '/v1/disputes/{disputeId}/close',
+        tag: 'Disputes',
+        summary: 'Close a dispute',
+        description: 'Accept the dispute: it is lost.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: disputeId,
+        body: closeDisputeParams,
+        response: disputeSchema,
+        sdk: 'disputes.close',
+    }),
+];

package/dist/esm/resources/payments/index.js

@@ -0,0 +1,24 @@
+import { chargeRoutes } from './charges.js';
+import { disputeRoutes } from './disputes.js';
+import { paymentIntentRoutes } from './paymentIntents.js';
+import { refundRoutes } from './refunds.js';
+import { setupIntentRoutes } from './setupIntents.js';
+import { socialRoutes } from './social.js';
+import { paymentIntentTestHelperRoutes } from './testHelpers.js';
+export * from './charges.js';
+export * from './disputes.js';
+export * from './paymentIntents.js';
+export * from './refunds.js';
+export * from './setupIntents.js';
+export * from './social.js';
+export * from './testHelpers.js';
+/** Payment intents, charges, refunds, disputes, setup intents, social payments. */
+export const paymentsRoutes = [
+    ...paymentIntentRoutes,
+    ...chargeRoutes,
+    ...refundRoutes,
+    ...disputeRoutes,
+    ...setupIntentRoutes,
+    ...socialRoutes,
+    ...paymentIntentTestHelperRoutes,
+];