@genesis-tech/genesispay-seller 0.13.1 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/CHANGELOG.md +206 -0
  2. package/README.md +670 -91
  3. package/dist/checkout-documents.d.ts +99 -0
  4. package/dist/checkout-documents.d.ts.map +1 -0
  5. package/dist/checkout-documents.js +155 -0
  6. package/dist/checkout-documents.js.map +1 -0
  7. package/dist/checkout-return.d.ts +41 -0
  8. package/dist/checkout-return.d.ts.map +1 -0
  9. package/dist/checkout-return.js +68 -0
  10. package/dist/checkout-return.js.map +1 -0
  11. package/dist/client.d.ts +318 -0
  12. package/dist/client.d.ts.map +1 -0
  13. package/dist/client.js +718 -0
  14. package/dist/client.js.map +1 -0
  15. package/dist/contract-mandates.d.ts +39 -0
  16. package/dist/contract-mandates.d.ts.map +1 -0
  17. package/dist/contract-mandates.js +98 -0
  18. package/dist/contract-mandates.js.map +1 -0
  19. package/dist/contract-usage.d.ts +29 -0
  20. package/dist/contract-usage.d.ts.map +1 -0
  21. package/dist/contract-usage.js +92 -0
  22. package/dist/contract-usage.js.map +1 -0
  23. package/dist/customers.d.ts +41 -0
  24. package/dist/customers.d.ts.map +1 -0
  25. package/dist/customers.js +76 -0
  26. package/dist/customers.js.map +1 -0
  27. package/dist/entitlements.d.ts +19 -0
  28. package/dist/entitlements.d.ts.map +1 -0
  29. package/dist/entitlements.js +30 -0
  30. package/dist/entitlements.js.map +1 -0
  31. package/dist/errors.d.ts +129 -0
  32. package/dist/errors.d.ts.map +1 -0
  33. package/dist/errors.js +273 -0
  34. package/dist/errors.js.map +1 -0
  35. package/dist/fulfillment-attempts.d.ts +29 -0
  36. package/dist/fulfillment-attempts.d.ts.map +1 -0
  37. package/dist/fulfillment-attempts.js +71 -0
  38. package/dist/fulfillment-attempts.js.map +1 -0
  39. package/dist/fulfillment.d.ts +152 -0
  40. package/dist/fulfillment.d.ts.map +1 -0
  41. package/dist/fulfillment.js +810 -0
  42. package/dist/fulfillment.js.map +1 -0
  43. package/dist/genesispay-settlement.d.ts +32 -0
  44. package/dist/genesispay-settlement.d.ts.map +1 -0
  45. package/dist/genesispay-settlement.js +500 -0
  46. package/dist/genesispay-settlement.js.map +1 -0
  47. package/dist/index.d.ts +22 -0
  48. package/dist/index.d.ts.map +1 -0
  49. package/dist/index.js +21 -0
  50. package/dist/index.js.map +1 -0
  51. package/dist/invoices.d.ts +111 -0
  52. package/dist/invoices.d.ts.map +1 -0
  53. package/dist/invoices.js +192 -0
  54. package/dist/invoices.js.map +1 -0
  55. package/dist/item-tax.d.ts +15 -0
  56. package/dist/item-tax.d.ts.map +1 -0
  57. package/dist/item-tax.js +19 -0
  58. package/dist/item-tax.js.map +1 -0
  59. package/dist/mandate-gate.d.ts +54 -0
  60. package/dist/mandate-gate.d.ts.map +1 -0
  61. package/dist/mandate-gate.js +183 -0
  62. package/dist/mandate-gate.js.map +1 -0
  63. package/dist/mandates.d.ts +189 -0
  64. package/dist/mandates.d.ts.map +1 -0
  65. package/dist/mandates.js +234 -0
  66. package/dist/mandates.js.map +1 -0
  67. package/dist/networks.d.ts +10 -0
  68. package/dist/networks.d.ts.map +1 -0
  69. package/dist/networks.js +23 -0
  70. package/dist/networks.js.map +1 -0
  71. package/dist/payment-gate.d.ts +98 -0
  72. package/dist/payment-gate.d.ts.map +1 -0
  73. package/dist/payment-gate.js +370 -0
  74. package/dist/payment-gate.js.map +1 -0
  75. package/dist/plans.d.ts +68 -0
  76. package/dist/plans.d.ts.map +1 -0
  77. package/dist/plans.js +127 -0
  78. package/dist/plans.js.map +1 -0
  79. package/dist/products.d.ts +170 -0
  80. package/dist/products.d.ts.map +1 -0
  81. package/dist/products.js +1317 -0
  82. package/dist/products.js.map +1 -0
  83. package/dist/resource.d.ts +47 -0
  84. package/dist/resource.d.ts.map +1 -0
  85. package/dist/resource.js +71 -0
  86. package/dist/resource.js.map +1 -0
  87. package/dist/strict-response.d.ts +21 -0
  88. package/dist/strict-response.d.ts.map +1 -0
  89. package/dist/strict-response.js +68 -0
  90. package/dist/strict-response.js.map +1 -0
  91. package/dist/usdc-amount.d.ts +7 -0
  92. package/dist/usdc-amount.d.ts.map +1 -0
  93. package/dist/usdc-amount.js +21 -0
  94. package/dist/usdc-amount.js.map +1 -0
  95. package/dist/webhooks.d.ts +352 -0
  96. package/dist/webhooks.d.ts.map +1 -0
  97. package/dist/webhooks.js +244 -0
  98. package/dist/webhooks.js.map +1 -0
  99. package/package.json +4 -3
package/dist/plans.js ADDED
@@ -0,0 +1,127 @@
1
+ // `genesispay.plans.*` — subscription plans over `/api/v1/plans`.
2
+ //
3
+ // A plan is the recurring sibling of a checkout link: it describes an amount
4
+ // per period and exposes a hosted `checkoutUrl` the customer signs a mandate
5
+ // on. Everything is scoped to the key's own account, so a plan owned by someone
6
+ // else answers 404 (GenesisPayNotFoundError) rather than 403 — the API is no
7
+ // plan-enumeration oracle, and the SDK does not paper over that.
8
+ import { GenesisPayConfigError } from "./errors.js";
9
+ import { asRecord, optionalString, requiredString, toAmountString, toCount, oneOf, } from "./resource.js";
10
+ export function createPlansResource(request,
11
+ /**
12
+ * Applies the client's `expectedPayTo` pin to the wallet the server froze
13
+ * onto the plan. A plan's destination is where every future renewal settles,
14
+ * so it is exactly the value the pin exists to guard.
15
+ */
16
+ assertPinnedDestination = () => { }) {
17
+ return {
18
+ create: async (input) => {
19
+ const body = await request({
20
+ method: "POST",
21
+ path: "/api/v1/plans",
22
+ operation: "POST /api/v1/plans",
23
+ action: "create a subscription plan",
24
+ body: {
25
+ title: input.title,
26
+ amountPerPeriod: input.amountPerPeriod,
27
+ periodDays: input.periodDays,
28
+ ...(input.description ? { description: input.description } : {}),
29
+ ...(input.prepaidCycles === undefined
30
+ ? {}
31
+ : { prepaidCycles: input.prepaidCycles }),
32
+ ...(input.destinationWallet
33
+ ? { destinationWallet: input.destinationWallet }
34
+ : {}),
35
+ ...(input.asset ? { asset: input.asset } : {}),
36
+ },
37
+ });
38
+ const plan = requirePlan(body, "POST /api/v1/plans");
39
+ assertPinnedDestination(plan.destinationWallet, "subscription plan");
40
+ return plan;
41
+ },
42
+ list: async () => {
43
+ const body = await request({
44
+ path: "/api/v1/plans",
45
+ operation: "GET /api/v1/plans",
46
+ action: "list subscription plans",
47
+ });
48
+ const plans = asRecord(body)?.plans;
49
+ if (!Array.isArray(plans)) {
50
+ // A list endpoint that answers 200 without a list is a broken contract,
51
+ // not an old backend. Returning [] here would hide it as "no plans yet".
52
+ throw new GenesisPayConfigError(`GenesisPay GET /api/v1/plans returned no plans array: ${JSON.stringify(body)}`);
53
+ }
54
+ // Individual entries stay tolerant: one unusable row must not lose the rest.
55
+ return plans
56
+ .map(asRecord)
57
+ .filter((raw) => raw !== null)
58
+ .filter((raw) => typeof raw.publicId === "string" && raw.publicId.length > 0)
59
+ .map(toSubscriptionPlan);
60
+ },
61
+ retrieve: async (publicId) => {
62
+ const id = requirePublicId(publicId, "plans.retrieve");
63
+ const body = await request({
64
+ path: `/api/v1/plans/${encodeURIComponent(id)}`,
65
+ operation: `GET /api/v1/plans/${id}`,
66
+ action: `retrieve subscription plan "${id}"`,
67
+ notFoundMessage: notFoundMessage(id),
68
+ });
69
+ return requirePlan(body, `GET /api/v1/plans/${id}`);
70
+ },
71
+ archive: async (publicId) => {
72
+ const id = requirePublicId(publicId, "plans.archive");
73
+ const body = await request({
74
+ method: "POST",
75
+ path: `/api/v1/plans/${encodeURIComponent(id)}/archive`,
76
+ operation: `POST /api/v1/plans/${id}/archive`,
77
+ action: `archive subscription plan "${id}"`,
78
+ notFoundMessage: notFoundMessage(id),
79
+ });
80
+ return requirePlan(body, `POST /api/v1/plans/${id}/archive`);
81
+ },
82
+ };
83
+ }
84
+ function notFoundMessage(id) {
85
+ return (`No GenesisPay subscription plan with publicId "${id}". Check the id and that ` +
86
+ `it belongs to the account this API key authenticates.`);
87
+ }
88
+ function requirePublicId(publicId, method) {
89
+ const id = publicId?.trim();
90
+ if (!id) {
91
+ throw new GenesisPayConfigError(`${method}(publicId) requires the publicId returned by plans.create().`);
92
+ }
93
+ return id;
94
+ }
95
+ function requirePlan(body, operation) {
96
+ const raw = asRecord(asRecord(body)?.plan);
97
+ if (!raw || typeof raw.publicId !== "string" || !raw.publicId) {
98
+ throw new GenesisPayConfigError(`GenesisPay ${operation} returned no plan: ${JSON.stringify(body)}`);
99
+ }
100
+ return toSubscriptionPlan(raw);
101
+ }
102
+ export function toSubscriptionPlan(raw) {
103
+ return {
104
+ id: requiredString(raw.id),
105
+ publicId: requiredString(raw.publicId),
106
+ title: requiredString(raw.title),
107
+ description: optionalString(raw.description),
108
+ asset: oneOf(raw.asset, ["USDC", "EURC"], "USDC"),
109
+ amountPerPeriod: toAmountString(raw.amountPerPeriod),
110
+ amountPerPeriodMinor: toAmountString(raw.amountPerPeriodMinor),
111
+ periodDays: toCount(raw.periodDays),
112
+ prepaidCycles: toCount(raw.prepaidCycles),
113
+ capPerChargeMinor: toAmountString(raw.capPerChargeMinor),
114
+ allowanceMinor: toAmountString(raw.allowanceMinor),
115
+ destinationWallet: requiredString(raw.destinationWallet),
116
+ chainId: toCount(raw.chainId),
117
+ // Degrade to "archived", not "active": a status this SDK version does not
118
+ // know (a future "paused", "deleted", …) must not read as "keep sending
119
+ // customers to this checkoutUrl". Mirrors mandate status degrading to the
120
+ // inert `pending_permit`.
121
+ status: oneOf(raw.status, ["active", "archived"], "archived"),
122
+ checkoutUrl: requiredString(raw.checkoutUrl),
123
+ createdAt: requiredString(raw.createdAt),
124
+ archivedAt: optionalString(raw.archivedAt),
125
+ };
126
+ }
127
+ //# sourceMappingURL=plans.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"plans.js","sourceRoot":"","sources":["../src/plans.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,170 @@
1
+ import { type ItemTax, type ItemTaxUpdate } from "./item-tax.js";
2
+ import { type GenesisPayRequest } from "./resource.js";
3
+ import type { CheckoutLink } from "./client.js";
4
+ import { GENESISPAY_API_VERSION, type ExpectedProductContract, type FulfillmentResource, type VerifiedPayment } from "./fulfillment.js";
5
+ export type ProductDelivery = {
6
+ type: "none";
7
+ } | {
8
+ type: "redirect";
9
+ url: string;
10
+ verifiedAt: string | null;
11
+ } | {
12
+ type: "gate";
13
+ resourceUrl: string;
14
+ method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
15
+ };
16
+ export type Product = {
17
+ taxConfig: ItemTax | null;
18
+ publicId: string;
19
+ name: string;
20
+ description: string | null;
21
+ imageUrl: string | null;
22
+ sku: string | null;
23
+ asset: "USDC" | "EURC";
24
+ /** Decimal price in `asset`, as the server normalized it (e.g. "2", "0.5"). */
25
+ price: string;
26
+ /** Same price in 6-decimal minor units, as a string (no precision loss). */
27
+ priceMinor: string;
28
+ /**
29
+ * Only an explicit `true` counts — an older backend that omits the field
30
+ * must not read as "archived", and a product this SDK cannot classify must
31
+ * not silently vanish from a catalogue sync.
32
+ */
33
+ archived: boolean;
34
+ /** Where a paying buyer's entitlement redirects; null until the seller sets it. */
35
+ fulfilmentUrl: string | null;
36
+ fulfilmentVerifiedAt: string | null;
37
+ /** Additive delivery contract; flat fulfilment fields remain for compatibility. */
38
+ delivery: ProductDelivery;
39
+ createdAt: string;
40
+ };
41
+ export type ProductCreateInput = {
42
+ /** Omitted means unconfigured; human checkout requires explicit item tax. */
43
+ taxConfig?: ItemTax;
44
+ name: string;
45
+ /** Decimal price, e.g. "2" or "2.00" — never a float. */
46
+ price: string;
47
+ description?: string;
48
+ imageUrl?: string;
49
+ /** The merchant's own key; unique per account, a repeat answers 409. */
50
+ sku?: string;
51
+ /** Defaults to USDC (the only settlement asset during the beta). */
52
+ asset?: "USDC";
53
+ delivery?: ProductDelivery;
54
+ };
55
+ export type ProductPaymentLink = {
56
+ /** The product's one canonical reusable link — mint again and you get the same one. */
57
+ link: CheckoutLink;
58
+ /** True only on the call that actually created the link. */
59
+ created: boolean;
60
+ };
61
+ export type ProductCheckoutCreateInput = {
62
+ expected: ExpectedProductContract;
63
+ clientReferenceId?: string | null;
64
+ metadata?: Record<string, string> | null;
65
+ returnUrl?: string | null;
66
+ cancelUrl?: string | null;
67
+ };
68
+ export type ProductCheckoutLink = {
69
+ object: "product_checkout_link";
70
+ linkId: string;
71
+ payUrl: string;
72
+ productContractVersion: typeof GENESISPAY_API_VERSION;
73
+ created: boolean;
74
+ requestId: string;
75
+ apiVersion: typeof GENESISPAY_API_VERSION;
76
+ };
77
+ export type ProductCheckoutCreationOptions = {
78
+ idempotencyKey: string;
79
+ };
80
+ export type ProductGatePurchase = {
81
+ product: NonNullable<VerifiedPayment["product"]> & {
82
+ quantity: 1;
83
+ };
84
+ payment: VerifiedPayment;
85
+ requestFingerprint: string;
86
+ };
87
+ export type ProductGate = {
88
+ /** Fetches the product and idempotently ensures its canonical reusable link. */
89
+ prime(): Promise<{
90
+ product: Product;
91
+ paymentLink: ProductPaymentLink;
92
+ }>;
93
+ /**
94
+ * Protect a registered resource. The handler may run again after a confirmed
95
+ * replay, so persist by `purchase.payment.attemptId` when effects are not
96
+ * naturally idempotent.
97
+ */
98
+ protect(request: Request, expected: ExpectedProductContract, handler: (request: Request, purchase: ProductGatePurchase) => Response | Promise<Response>): Promise<Response>;
99
+ };
100
+ export interface ProductsResource {
101
+ create(input: ProductCreateInput): Promise<Product>;
102
+ /** Active products; pass `includeArchived: true` for the whole catalogue. */
103
+ list(opts?: {
104
+ includeArchived?: boolean;
105
+ }): Promise<Product[]>;
106
+ retrieve(publicId: string): Promise<Product>;
107
+ /**
108
+ * Set or clear (`null`) the https fulfilment URL — where a paying buyer's
109
+ * entitlement redirects. Changing it resets the server's verification stamp.
110
+ */
111
+ update(publicId: string, input: {
112
+ fulfilmentUrl: string | null;
113
+ } | {
114
+ delivery: ProductDelivery;
115
+ } | ItemTaxUpdate): Promise<Product>;
116
+ /**
117
+ * Stops NEW payment-link mints; the existing canonical link stays payable
118
+ * (a buyer mid-checkout is not punished for a catalogue edit). Archiving
119
+ * twice is a no-op that returns the same product.
120
+ */
121
+ archive(publicId: string): Promise<Product>;
122
+ /**
123
+ * Mint the product's canonical reusable payment link, or return the existing
124
+ * one with `created: false`. Idempotent by construction: the one-live-link
125
+ * rule is a database unique index, so even concurrent mints converge on the
126
+ * same link.
127
+ */
128
+ createPaymentLink(publicId: string): Promise<ProductPaymentLink>;
129
+ /** Fail-closed readiness check against the seller's current product contract. */
130
+ assertContract(expected: ExpectedProductContract): Promise<void>;
131
+ /** Create one product-backed single-use link with seller-account-scoped idempotency. */
132
+ createCheckout(input: ProductCheckoutCreateInput, options: ProductCheckoutCreationOptions): Promise<ProductCheckoutLink>;
133
+ /**
134
+ * The product's payable URL — convenience for
135
+ * `createPaymentLink(publicId)` → `link.payUrl`. The returned URL embeds the
136
+ * link's `inv_` id, which changes when the link is archived and reminted
137
+ * (e.g. a wallet migration): resolve it at render time, never hardcode it.
138
+ * The mint is idempotent, but it is still a write — don't put it in a hot
139
+ * render path uncached; prefer `permalink` where stability is what you need.
140
+ */
141
+ checkoutUrl(publicId: string): Promise<string>;
142
+ /**
143
+ * The product's PERMANENT checkout URL (`{baseUrl}/pay/p/{publicId}`) —
144
+ * stable across every link remint, resolved server-side on every request.
145
+ * Pure string builder: no network call, no mint. This is the URL to embed
146
+ * in a shop's buy button.
147
+ */
148
+ permalink(publicId: string): string;
149
+ gate(publicId: string): ProductGate;
150
+ }
151
+ export declare function createProductsResource(request: GenesisPayRequest,
152
+ /**
153
+ * Applies the client's `expectedPayTo` pin to the wallet the server froze
154
+ * onto the minted link — the destination every sale of this product settles
155
+ * to, which is exactly the value the pin exists to guard.
156
+ */
157
+ assertPinnedDestination: (wallet: unknown, what: string) => void,
158
+ /** The client's raw-link mapper, so link shapes cannot drift between resources. */
159
+ toLink: (raw: Record<string, unknown>) => CheckoutLink,
160
+ /** The client's origin (no trailing slash) — the base of `permalink()`. */
161
+ baseUrl: string, verifyFulfillment: FulfillmentResource["verify"], rawGateRequest?: (publicId: string, body: Record<string, unknown>) => Promise<Response>, strictRequest?: (input: {
162
+ method?: "GET" | "POST";
163
+ path: string;
164
+ body?: unknown;
165
+ headers?: Record<string, string>;
166
+ }) => Promise<Response>): ProductsResource;
167
+ export declare function toProduct(raw: Record<string, unknown>): Product;
168
+ /** Canonical SHA-256 gate intent fingerprint used in ExpectedProductContract. */
169
+ export declare function createGateRequestFingerprint(request: Request): Promise<string>;
170
+ //# sourceMappingURL=products.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"products.d.ts","sourceRoot":"","sources":["../src/products.ts"],"names":[],"mappings":"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"}