@blockmoblabs/cryptopay 0.1.1 → 0.2.0

package/README.md

@@ -16,7 +16,7 @@ npm install @blockmoblabs/cryptopay
 import { CryptoPay } from '@blockmoblabs/cryptopay';
 
 const cryptopay = new CryptoPay({
-  apiKey: process.env.CRYPTOPAY_API_KEY!,   // cp_test_… or cp_live_…
+  apiKey: process.env.CRYPTOPAY_API_KEY!,   // cp_live_… from Dashboard -> API keys
   baseUrl: process.env.CRYPTOPAY_API_URL,   // only when self-hosting
 });
 
@@ -32,8 +32,7 @@ const intent = await cryptopay.createIntent({
 });
 ```
 
-The key decides the merchant **and** the mode — there is no mode flag to get wrong. `cryptopay.mode`
-reports which one you are on.
+The key identifies the merchant; there is no mode flag to get wrong.
 
 | Method | What |
 | --- | --- |
@@ -41,10 +40,39 @@ reports which one you are on.
 | `getIntent(id)` | Read one payment, including its deposit sessions. |
 | `listIntents(query)` | Page through payments; `search` matches any of your references. |
 | `cancelIntent(id)` | Cancel an unpaid payment. Refused once completed. |
+| `createSubscription(input)` | Bill a customer every week, month or year. See below. |
+| `getSubscription(id)` / `listSubscriptions()` | Read subscriptions and their next due date. |
+| `cancelSubscription(id)` | Stop future payments. |
 | `verifyWebhook(opts)` | Verify and parse a webhook. Throws on anything suspect. |
 
 Non-2xx responses throw `CryptoPayError` with `status` and `body`.
 
+## Subscriptions
+
+Crypto cannot be pulled from a wallet, so a subscription is a recurring invoice. Three days before
+each due date the customer is emailed a payment link, then reminded once a day. If it is still
+unpaid three days after the due date, the subscription lapses.
+
+```ts
+const sub = await cryptopay.createSubscription({
+  amountUsd: 20,
+  customerEmail: 'user@example.com',
+  interval: 'month',                  // 'week' | 'month' | 'year'
+  firstDueAt: '2026-11-02',           // later payments stay on the 2nd
+  reference: 'sub_221',               // comes back as customer.subscriptionRef
+  description: 'Pro plan',            // shown to the customer in the emails
+});
+```
+
+In your webhook handler:
+
+| Event | What to do |
+| --- | --- |
+| `payment.completed` with `customer.subscriptionRef` | A period was paid. Extend access. |
+| `subscription.renewed` | Same moment; `event.subscription.dueAt` is the next due date. |
+| `subscription.payment_due` | An invoice opened. `event.subscription.checkoutUrl` is the link, if you want to send your own message. |
+| `subscription.lapsed` | Unpaid after the grace period. Remove access. |
+
 ## Browser
 
 ```ts
@@ -67,7 +95,7 @@ checkout's origin can drive the modal.
 
 ## Webhooks
 
-Pass the **raw** body — a re-serialized object will not match the signature.
+Pass the **raw** body: a re-serialized object will not match the signature.
 
 ```ts
 app.post('/webhooks/cryptopay', express.raw({ type: 'application/json' }), async (req, res) => {
@@ -100,18 +128,14 @@ old event does not get through. Delivery is at-least-once: dedupe on `event.id`.
 Events: `payment.created`, `payment.detected`, `payment.confirming`, `payment.underpaid`,
 `payment.completed`, `payment.expired`, `payment.failed`.
 
-## Test mode
-
-A test key runs the whole lifecycle against a simulator — real intents, statuses and webhooks, no
-chain and no money. The deposit address is `cptest_…`, deliberately invalid on every network, and the
-payment confirms on a timer: detected within ~15s and confirmed within ~30s, since the watcher that
-advances it ticks every 15 seconds. In an automated test, call `POST /sessions/:id/recheck` (what *I
-have paid* does in the checkout) to confirm immediately instead of sleeping.
+## Trying it out
 
-Going live is one environment variable: the key changes, the code does not.
+Accounts are live from sign-up. Make a small real payment to see the whole lifecycle, or create a
+payment link from the dashboard and open its checkout to see what your customers see. Events can be
+re-sent from Dashboard -> Webhooks while you build your handler.
 
 ## Fees
 
-$2 flat per successful payment, charged once on completion. It comes off your side — the payer is
+1% per successful payment with a $0.50 minimum, charged once on completion. It comes off your side: the payer is
 asked for exactly the invoice amount. On a $40 payment, `fee` is
-`{ grossUsd: 40, feeUsd: 2, netUsd: 38 }`.
+`{ grossUsd: 40, feeUsd: 0.5, netUsd: 39.5 }`.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { type CreateIntentInput, type PaymentIntent, type WebhookEvent } from './types.js';
+import { type CreateIntentInput, type CreateSubscriptionInput, type PaymentIntent, type Subscription, type WebhookEvent } from './types.js';
 export * from './types.js';
 export type CryptoPayOptions = {
     /** `cp_test_…` or `cp_live_…`. The key decides the mode; there is no mode flag to get wrong. */
@@ -41,6 +41,18 @@ export declare class CryptoPay {
         intents: PaymentIntent[];
         nextCursor: string | null;
     }>;
+    /**
+     * Bill a customer on a schedule. Three days before each due date they are emailed a payment link,
+     * then reminded daily; unpaid three days after it, the subscription lapses. Each payment arrives
+     * as an ordinary `payment.completed` webhook carrying your `reference` as `subscriptionRef`.
+     */
+    createSubscription(input: CreateSubscriptionInput): Promise<Subscription>;
+    getSubscription(id: string): Promise<Subscription>;
+    listSubscriptions(): Promise<{
+        subscriptions: Subscription[];
+    }>;
+    /** Stops future payments. Safe to call twice. */
+    cancelSubscription(id: string): Promise<Subscription>;
     /**
      * Verify a webhook and return its parsed body. Pass the RAW request body — a re-serialized object
      * will not match the signature. Throws if the signature, the headers, or the timestamp is wrong,

package/dist/index.js

@@ -53,6 +53,24 @@ export class CryptoPay {
         const suffix = params.toString();
         return this.request('GET', `/payment-intents${suffix ? `?${suffix}` : ''}`);
     }
+    /**
+     * Bill a customer on a schedule. Three days before each due date they are emailed a payment link,
+     * then reminded daily; unpaid three days after it, the subscription lapses. Each payment arrives
+     * as an ordinary `payment.completed` webhook carrying your `reference` as `subscriptionRef`.
+     */
+    createSubscription(input) {
+        return this.request('POST', '/subscriptions', { body: input });
+    }
+    getSubscription(id) {
+        return this.request('GET', `/subscriptions/${encodeURIComponent(id)}`);
+    }
+    listSubscriptions() {
+        return this.request('GET', '/subscriptions');
+    }
+    /** Stops future payments. Safe to call twice. */
+    cancelSubscription(id) {
+        return this.request('POST', `/subscriptions/${encodeURIComponent(id)}/cancel`);
+    }
     /**
      * Verify a webhook and return its parsed body. Pass the RAW request body — a re-serialized object
      * will not match the signature. Throws if the signature, the headers, or the timestamp is wrong,

package/dist/types.d.ts

@@ -76,7 +76,41 @@ export type CreateIntentInput = {
     /** Repeating a request with the same key returns the original intent instead of charging twice. */
     idempotencyKey?: string;
 };
-export type WebhookEventType = 'payment.created' | 'payment.detected' | 'payment.confirming' | 'payment.underpaid' | 'payment.completed' | 'payment.expired' | 'payment.failed' | 'sweep.failed';
+export type WebhookEventType = 'payment.created' | 'payment.detected' | 'payment.confirming' | 'payment.underpaid' | 'payment.completed' | 'payment.expired' | 'payment.failed' | 'sweep.failed' | 'subscription.payment_due' | 'subscription.renewed' | 'subscription.lapsed';
+export type CreateSubscriptionInput = {
+    /** Charged every interval. 0.50 to 1,000,000, at most 2 decimals. */
+    amountUsd: number;
+    /** Who is billed. Payment links and reminders are emailed here. */
+    customerEmail: string;
+    interval: 'week' | 'month' | 'year';
+    /** When the first payment is due (ISO date). Left out: now. Later ones keep the same day. */
+    firstDueAt?: string;
+    customerRef?: string;
+    /** Your own id for this subscription. Comes back as `customer.subscriptionRef` on every payment. */
+    reference?: string;
+    /** What is being paid for, as the customer reads it in the emails. */
+    description?: string;
+    metadata?: Record<string, unknown>;
+};
+export type Subscription = {
+    id: string;
+    mode: ApiMode;
+    status: 'active' | 'lapsed' | 'cancelled';
+    customerEmail: string;
+    customerRef: string | null;
+    reference: string | null;
+    description: string | null;
+    amountUsd: number;
+    interval: 'week' | 'month' | 'year';
+    /** When the period now being collected is due. Null once the subscription has ended. */
+    dueAt: string | null;
+    periodsPaid: number;
+    /** The open invoice (a payment intent), once the customer has been asked to pay it. */
+    intentId: string | null;
+    metadata: unknown;
+    endedAt: string | null;
+    createdAt: string;
+};
 export type WebhookEvent = {
     id: string;
     type: WebhookEventType;
@@ -99,6 +133,10 @@ export type WebhookEvent = {
         feeUsd: number;
         netUsd: number;
     } | null;
+    /** On `subscription.*` events. `checkoutUrl` is set on `subscription.payment_due`. */
+    subscription?: Subscription & {
+        checkoutUrl?: string | null;
+    };
     payment: {
         sessionId: string;
         chain: Chain;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockmoblabs/cryptopay",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "CryptoPay crypto payment infrastructure: create payment intents, open the checkout, verify webhooks.",
   "license": "MIT",
   "type": "module",