@buclepay/node 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 buclePay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @buclepay/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official Node.js SDK for [buclePay](https://buclepay.com): recurring payments in stablecoins (USDT, USDC) without custody. No dependencies, Node 18+.
+
+```bash
+npm i @buclepay/node
+```
+
+Your API key (`bp_…`, Dashboard › Developers › API) lives **only on your server**, never in an app or a web page.
+
+```js
+import { BuclePay } from '@buclepay/node';
+const bp = new BuclePay(process.env.BUCLEPAY_API_KEY);
+
+// 1. Create a payment link with your own id, open link.url in your app or site
+const { data: link } = await bp.paymentLinks.create({
+  amount_usd: 49.99, interval: 'month', description: 'Pro plan',
+  client_reference_id: 'user_123', metadata: { plan: 'pro' },
+});
+
+// 2. Receive the signed webhook and activate the service
+app.post('/webhooks/buclepay', express.raw({ type: 'application/json' }), (req, res) => {
+  const event = bp.webhooks.constructEvent(req.body.toString('utf8'), req.get('buclepay-signature'), process.env.BUCLEPAY_WHSEC);
+  if (event.type === 'payment.succeeded') activate(event.data.object.subscription.client_reference_id);
+  res.sendStatus(200);
+});
+```
+
+| Method | What it does |
+|---|---|
+| `paymentLinks.create / retrieve / list` | Payment links (one-time, plan or installments) |
+| `subscriptions.retrieve / list` | Filter by `client_reference_id`, `email`, `status` |
+| `plans.list`, `customers.list`, `payments.list` | Your plans, customers and payments |
+| `events.list` | Same events as the webhooks |
+| `perks.list / create`, `customers.perks(id)` | bucleScore rewards (below) |
+| `webhooks.constructEvent / verifySignature` | Verify the `buclepay-signature` header |
+
+## bucleScore: reward your best customers
+
+Each payer has a bucleScore built from all their payments on buclePay. **You never see the score or the history.** You see the customer's **level (1–4)** only if they chose to show it to you, and you use it to give rewards: discounts (1–50%), free charges (1–3), gifts, priority or early access.
+
+```js
+await bp.perks.create({ min_level: 3, kind: 'discount_pct', value: 10, title: '10% off your renewal' });
+const { data } = await bp.customers.perks('cus_…'); // { level_shared, level, perks }
+```
+
+The level is for rewards only. Never use it to deny service, ask for deposits, offer credit or installments, or charge differently.
+
+Errors are thrown as `BuclePayError` with `status`, `code` and `param`.
+
+License: MIT.

package/index.d.ts

@@ -0,0 +1,108 @@
+export class BuclePayError extends Error { status: number; code: string; param?: string }
+
+export type Metadata = Record<string, string | number | boolean>;
+
+export interface PaymentLinkParams {
+  /** Amount in USD (minimum 1.99, cents allowed). Not sent with `plan_id`. */
+  amount_usd?: number;
+  /** With `interval` the link is a subscription; without it, a one-time payment. */
+  interval?: 'day' | 'week' | 'month' | 'year';
+  /** day: 1–365 · week: 1 or 2 · month: 1 or 3 · year: 1 */
+  interval_count?: number;
+  /** Installments: charging stops by itself after the last one is paid (2–120). */
+  max_charges?: number;
+  trial_days?: number;
+  /** Subscribe to a plan created in the dashboard. */
+  plan_id?: string;
+  description?: string;
+  /** Up to 20 pairs; keys of 1–40 characters (letters, digits, _ . -); values up to 500. No personal data. */
+  metadata?: Metadata;
+  /** Your own id (user, order…, up to 200 characters). Comes back in the API and in every webhook for that subscription. */
+  client_reference_id?: string;
+  /** 1–90; otherwise your Settings › Charges default (3 days). */
+  expires_in_days?: number;
+  /** Where the customer returns when done: a public https:// URL or your app scheme (myapp://pay). bp_link, bp_status and bp_subscription are appended. */
+  success_url?: string;
+  /** Same, for "Cancel and go back" or when the payment fails (bp_status=canceled|failed). */
+  cancel_url?: string;
+}
+
+export interface PaymentLink {
+  id: string; object: 'payment_link'; url: string; type: 'once' | 'plan' | 'invoice' | 'open'; status: 'active' | 'expired' | 'disabled';
+  amount_usd: number; description: string | null; invoice_number: string | null; plan_id: string;
+  interval: string | null; interval_count: number | null; max_charges: number | null; trial_days: number;
+  expires_at: string | null; created_at: string; client_reference_id: string | null; metadata: Record<string, string>;
+  /** true once the customer has signed; `subscription_id` then points to their subscription. */
+  completed: boolean; subscription_id: string | null;
+  success_url: string | null; cancel_url: string | null;
+}
+
+export interface Subscription {
+  id: string; object: 'subscription'; status: 'trialing' | 'active' | 'grace' | 'suspended' | 'canceled' | 'ended' | 'paused';
+  /** true = provide the service (paid up, in trial or in grace period). */
+  active: boolean;
+  plan: string; plan_id: string; amount_usd: number; interval: string; interval_count: number; max_charges: number | null; charges_made: number; token: 'USDT' | 'USDC' | null;
+  next_charge_at: string | null; trial_end: string | null; cancel_at_period_end: boolean; canceled_at: string | null; ended_at: string | null; created_at: string;
+  customer: { id: string; email: string | null }; label: string | null;
+  client_reference_id: string | null; metadata: Record<string, string>;
+}
+
+export interface Invoice {
+  id: string; object: 'invoice'; number: string; status: string; subscription_id: string;
+  amount_usd: number; subtotal_usd: number; discount_usd: number; fee_usd: number; net_usd: number; fee_bps: number;
+  period_start: string; period_end: string; due_at: string; paid_at: string | null;
+  payment: { token: string | null; chain_id: number | null; chain: string | null; tx_hash: string; explorer_url: string | null } | null;
+  subscription: Subscription | null;
+}
+
+export interface Plan {
+  id: string; object: 'plan'; name: string; amount_usd: number; interval: string; interval_count: number; trial_days: number;
+  max_charges: number | null; tokens: string[]; created_at: string; active_subscriptions: number;
+}
+
+export type EventType =
+  | 'payment.succeeded' | 'payment.failed' | 'payment.retry_scheduled' | 'invoice.paid' | 'invoice.notice_undeliverable'
+  | 'subscription.created' | 'subscription.past_due' | 'subscription.suspended' | 'subscription.reactivated' | 'subscription.canceled' | 'subscription.ended'
+  | 'mandate.registered' | 'mandate.revoked' | 'merchant.restricted' | (string & {});
+
+export interface BuclePayEvent {
+  id: string; type: EventType; created: number; api_version: string;
+  /** Event details (ids, reason…) plus `object`: the invoice (payment.*, invoice.*) or the subscription (subscription.*, mandate.*). */
+  data: Record<string, unknown> & { object?: Invoice | Subscription };
+}
+
+export type PerkKind = 'discount_pct' | 'free_period' | 'gift' | 'priority' | 'early_access' | 'custom';
+export interface Perk { id: string; object: 'perk'; min_level: 1 | 2 | 3 | 4; kind: PerkKind; value: number | null; title: string }
+export interface PerkParams { min_level: 1 | 2 | 3 | 4; kind: PerkKind; /** discount_pct 1–50 · free_period 1–3 · the rest take no value */ value?: number; title: string }
+export interface CustomerPerks { object: 'customer_perks'; customer: string; /** the customer agreed to show you their level */ level_shared: boolean; level: 1 | 2 | 3 | 4 | null; perks: Perk[] }
+
+export class BuclePay {
+  constructor(apiKey: string, opts?: { baseUrl?: string; timeoutMs?: number; fetch?: typeof fetch });
+  paymentLinks: {
+    create(params: PaymentLinkParams): Promise<{ data: PaymentLink }>;
+    retrieve(id: string): Promise<{ data: PaymentLink }>;
+    list(params?: { client_reference_id?: string; limit?: number }): Promise<{ data: PaymentLink[] }>;
+  };
+  subscriptions: {
+    retrieve(id: string): Promise<{ data: Subscription }>;
+    list(params?: { client_reference_id?: string; email?: string; status?: string }): Promise<{ data: Subscription[] }>;
+  };
+  plans: { list(): Promise<{ data: Plan[] }> };
+  customers: {
+    list(): Promise<{ data: unknown[] }>;
+    /** Level (only if the customer agreed to show it to you) and the rewards it unlocks. Never the score or the history. */
+    perks(id: string): Promise<{ data: CustomerPerks }>;
+  };
+  /** Rewards by bucleScore level. Rewards only: never deposits, installments or credit terms. */
+  perks: { list(): Promise<{ data: Perk[] }>; create(params: PerkParams): Promise<{ data: Perk }> };
+  payments: { list(): Promise<{ data: unknown[] }> };
+  events: { list(params?: { type?: string; starting_after?: string; limit?: number }): Promise<{ data: BuclePayEvent[]; has_more: boolean }> };
+  webhooks: {
+    constructEvent(body: string, signatureHeader: string, secret: string, opts?: { toleranceSeconds?: number; now?: number }): BuclePayEvent;
+    verifySignature(body: string, signatureHeader: string, secret: string, opts?: { toleranceSeconds?: number; now?: number }): boolean;
+  };
+}
+
+export function signPayload(secret: string, body: string, timestamp: number): string;
+export function verifySignature(body: string, signatureHeader: string, secret: string, opts?: { toleranceSeconds?: number; now?: number }): boolean;
+export function constructEvent(body: string, signatureHeader: string, secret: string, opts?: { toleranceSeconds?: number; now?: number }): BuclePayEvent;

package/index.js

@@ -0,0 +1,105 @@
+// @buclepay/node — buclePay API v1 client and webhook verification. No dependencies (Node ≥ 18 fetch and crypto).
+// Same style as Stripe: bp.paymentLinks.create(...), bp.subscriptions.retrieve(...), bp.webhooks.constructEvent(...).
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export class BuclePayError extends Error {
+  constructor(message, { status = 0, code = 'error', param = undefined } = {}) {
+    super(message);
+    this.name = 'BuclePayError';
+    this.status = status;
+    this.code = code;
+    this.param = param;
+  }
+}
+
+const qs = (o = {}) => {
+  const p = new URLSearchParams();
+  for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') p.set(k, String(v));
+  const s = p.toString();
+  return s ? `?${s}` : '';
+};
+
+export class BuclePay {
+  /**
+   * @param {string} apiKey `bp_…` key (Dashboard › Developers › API). Server only: never in an app or a web page.
+   * @param {{ baseUrl?: string, timeoutMs?: number, fetch?: typeof fetch }} [opts]
+   */
+  constructor(apiKey, opts = {}) {
+    if (typeof apiKey !== 'string' || !/^bp_[A-Za-z0-9_-]{20,80}$/.test(apiKey)) throw new BuclePayError('Missing or malformed API key (bp_…)', { code: 'invalid_api_key' });
+    this.apiKey = apiKey;
+    this.baseUrl = (opts.baseUrl ?? 'https://app.buclepay.com').replace(/\/$/, '');
+    this.timeoutMs = opts.timeoutMs ?? 15_000;
+    this._fetch = opts.fetch ?? globalThis.fetch;
+
+    this.paymentLinks = {
+      /** A one-time payment (`amount_usd`), a subscription with its own price (`amount_usd` + `interval`) or one of your plans (`plan_id`). */
+      create: (params) => this._request('POST', '/payment_links', params),
+      retrieve: (id) => this._request('GET', `/payment_links/${encodeURIComponent(id)}`),
+      list: (params) => this._request('GET', `/payment_links${qs(params)}`),
+    };
+    this.subscriptions = {
+      retrieve: (id) => this._request('GET', `/subscriptions/${encodeURIComponent(id)}`),
+      /** Filters: `client_reference_id`, `email`, `status`. */
+      list: (params) => this._request('GET', `/subscriptions${qs(params)}`),
+    };
+    this.plans = { list: () => this._request('GET', '/plans') };
+    this.customers = {
+      list: () => this._request('GET', '/customers'),
+      /** Level (only if the customer agreed to show it to you) and the rewards it unlocks. Never the score or the history. */
+      perks: (id) => this._request('GET', `/customers/${encodeURIComponent(id)}/perks`),
+    };
+    this.perks = {
+      /** Rewards by bucleScore level that you define. Rewards only: never deposits, installments or credit terms. */
+      list: () => this._request('GET', '/perks'),
+      create: (params) => this._request('POST', '/perks', params),
+    };
+    this.payments = { list: () => this._request('GET', '/payments') };
+    this.events = {
+      /** The same events sent by webhook; use it to catch up after downtime. Cursor: `starting_after`. */
+      list: (params) => this._request('GET', `/events${qs(params)}`),
+    };
+    this.webhooks = { constructEvent: constructEvent, verifySignature: verifySignature };
+  }
+
+  async _request(method, path, body) {
+    let res;
+    try {
+      res = await this._fetch(`${this.baseUrl}/api/v1${path}`, {
+        method,
+        headers: { authorization: `Bearer ${this.apiKey}`, ...(body === undefined ? {} : { 'content-type': 'application/json' }), 'user-agent': '@buclepay/node/0.1' },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (e) {
+      throw new BuclePayError(`Could not reach buclePay: ${e?.message ?? e}`, { code: 'connection_error' });
+    }
+    let json = null;
+    try { json = await res.json(); } catch { /* empty or non-JSON body */ }
+    if (!res.ok) {
+      const err = json?.error ?? {};
+      throw new BuclePayError(err.message ?? `HTTP ${res.status}`, { status: res.status, code: err.code ?? 'error', param: err.param });
+    }
+    return json;
+  }
+}
+
+/** Webhook signature: header `buclepay-signature: t=<unix>,v1=<hmac_sha256(secret, "<t>.<body>")>`. */
+export function signPayload(secret, body, timestamp) {
+  return `t=${timestamp},v1=${createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex')}`;
+}
+
+/** true if the signature is valid and recent (5 min by default). `body` must be the EXACT raw text received; never re-serialize the JSON. */
+export function verifySignature(body, header, secret, { toleranceSeconds = 300, now = Date.now() } = {}) {
+  const m = /t=(\d+),v1=([0-9a-f]{64})/.exec(String(header ?? ''));
+  if (!m || typeof body !== 'string' || !secret) return false;
+  if (Math.abs(now / 1000 - Number(m[1])) > toleranceSeconds) return false;
+  const want = Buffer.from(signPayload(secret, body, Number(m[1])).split('v1=')[1]);
+  const got = Buffer.from(m[2]);
+  return want.length === got.length && timingSafeEqual(want, got);
+}
+
+/** Verifies the signature and returns the parsed event; throws BuclePayError if anything is off (reply 400 and process nothing). */
+export function constructEvent(body, header, secret, opts) {
+  if (!verifySignature(body, header, secret, opts)) throw new BuclePayError('Invalid or expired webhook signature', { code: 'invalid_signature', status: 400 });
+  try { return JSON.parse(body); } catch { throw new BuclePayError('Webhook body is not JSON', { code: 'invalid_payload', status: 400 }); }
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@buclepay/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "buclePay for Node: create payment links, read subscriptions, verify webhooks and manage bucleScore rewards. No dependencies.",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "homepage": "https://buclepay.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/buclepay/buclepay.git",
+    "directory": "sdk/node"
+  },
+  "bugs": {
+    "url": "https://github.com/buclepay/buclepay/issues"
+  },
+  "keywords": [
+    "buclepay",
+    "payments",
+    "recurring",
+    "subscriptions",
+    "stablecoins",
+    "usdt",
+    "usdc",
+    "crypto",
+    "webhooks",
+    "non-custodial"
+  ],
+  "scripts": {
+    "test": "node --test"
+  }
+}