@flopay/node 0.1.0

package/README.md

@@ -0,0 +1,157 @@
+# @flopay/node
+
+Server-side FloPay SDK for Node.js. Creates checkout sessions via the billing API, manages Stripe customers, and verifies webhooks.
+
+## Installation
+
+```bash
+pnpm add @flopay/node
+```
+
+Depends on `stripe` (^17.0.0) and `@flopay/shared`.
+
+## Quick Start
+
+### Initialize
+
+```ts
+import { FloPay } from '@flopay/node';
+
+const flopay = new FloPay('sk_test_...');
+```
+
+### Create a Checkout Session (Billing API)
+
+```ts
+const result = await flopay.checkout.sessions.create({
+  billingApiUrl: 'https://billing.example.com',
+  checkoutBaseUrl: 'https://checkout.example.com',
+  clientId: 'client_123',
+  items: [{
+    providerItemId: 'prod_abc',
+    providerItemName: 'Pro Plan',
+    totalAmount: 49.99,
+    overrideAmount: 24.99,
+    currency: 'USD',
+  }],
+  subscriptions: [{
+    providerPlanId: 'plan_xyz',
+    providerPlanName: 'Monthly Plan',
+    totalAmount: 9.99,
+    currency: 'USD',
+  }],
+  account: {
+    userId: 'user_1',
+    email: 'user@example.com',
+    firstName: 'John',
+    lastName: 'Doe',
+  },
+  successUrl: 'https://example.com/success',
+  cancelUrl: 'https://example.com/cancel',
+  checkoutMode: 'confirm',   // 'confirm' | 'auto' | 'full'
+  couponCodes: ['SAVE10'],
+  tagsData: { googleContainerId: 'GTM-XXXX' },
+  redirectParams: { email: 'user@example.com', mode: 'confirm' },
+  timeoutMs: 12000,
+});
+
+// result = { status: 201, redirectUrl: 'https://checkout.example.com/secure?id=uuid&...' }
+// result = { status: 204 }  (payment method already on file)
+```
+
+### Retrieve / Expire a Checkout Session (Stripe Direct)
+
+```ts
+const session = await flopay.checkout.sessions.retrieve('cs_test_...');
+// { id, clientSecret, mode, status, amount, currency, metadata }
+
+const expired = await flopay.checkout.sessions.expire('cs_test_...');
+
+const lineItems = await flopay.checkout.sessions.listLineItems('cs_test_...');
+// [{ price: 'price_xxx', quantity: 1 }]
+```
+
+### Manage Customers
+
+```ts
+const customer = await flopay.customers.create({
+  email: 'user@example.com',
+  name: 'John Doe',
+  metadata: { plan: 'pro' },
+});
+// { id: 'cus_xxx', email: '...', firstName: 'John', lastName: 'Doe' }
+
+const retrieved = await flopay.customers.retrieve('cus_xxx');
+
+const updated = await flopay.customers.update('cus_xxx', {
+  name: 'Jane Doe',
+  metadata: { plan: 'enterprise' },
+});
+```
+
+### Verify Webhooks
+
+```ts
+import { FloPay } from '@flopay/node';
+
+const flopay = new FloPay('sk_test_...');
+
+// In your webhook handler (e.g. Express, Next.js API route):
+const event = flopay.webhooks.constructEvent(
+  requestBody,        // raw body string or Buffer
+  signatureHeader,    // Stripe-Signature header
+  'whsec_...',        // webhook signing secret
+);
+
+console.log(event.type);     // e.g. 'checkout.session.completed'
+console.log(event.data);     // event payload
+console.log(event.created);  // unix timestamp
+```
+
+## API Reference
+
+### Constructor
+
+```ts
+new FloPay(secretKey: string, options?: FloPayNodeOptions)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `secretKey` | `string` | Stripe secret key (`sk_test_...` or `sk_live_...`). Required. |
+| `options.apiVersion` | `string?` | API version override |
+| `options.stripeSecretKey` | `string?` | Explicit Stripe key (for future multi-provider support) |
+
+### `flopay.checkout.sessions`
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `create(params)` | `Promise<CheckoutSessionResult>` | Creates a session via billing API (`POST /v1/checkouts/sessions`). Returns `{ status: 201, redirectUrl }` or `{ status: 204 }`. |
+| `retrieve(id)` | `Promise<CheckoutSession>` | Retrieves a Stripe checkout session and normalizes it |
+| `expire(id)` | `Promise<CheckoutSession>` | Expires a Stripe checkout session |
+| `listLineItems(id)` | `Promise<LineItem[]>` | Lists line items for a Stripe checkout session |
+
+### `flopay.customers`
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `create(params)` | `Promise<Customer>` | Creates a Stripe customer |
+| `retrieve(id)` | `Promise<Customer>` | Retrieves a Stripe customer. Throws if deleted. |
+| `update(id, params)` | `Promise<Customer>` | Updates a Stripe customer |
+
+### `flopay.webhooks`
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `constructEvent(payload, signature, secret)` | `WebhookEvent` | Verifies and parses a Stripe webhook event |
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `FloPayNodeOptions` | Constructor options |
+| `CreateSessionParams` | Full session creation parameters (from `@flopay/shared`) |
+| `CheckoutSessionResult` | `{ status: 201, redirectUrl }` / `{ status: 204 }` / `{ status: number }` |
+| `CheckoutSession` | Normalized session: `id`, `clientSecret`, `mode`, `status`, `amount`, `currency`, `metadata` |
+| `Customer` | `id`, `email`, `firstName?`, `lastName?` |
+| `WebhookEvent` | `id`, `type`, `data`, `created` |

package/dist/index.cjs

@@ -0,0 +1,260 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FloPay: () => FloPay
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/flopay-node.ts
+var import_stripe = __toESM(require("stripe"), 1);
+var import_shared = require("@flopay/shared");
+var FloPay = class {
+  constructor(secretKey, options) {
+    if (!secretKey) {
+      throw new import_shared.FloPayError(
+        "A secret key is required to initialize the FloPay server SDK.",
+        "authentication_error"
+      );
+    }
+    this.stripe = new import_stripe.default(secretKey, {
+      apiVersion: "2025-04-30.basil",
+      appInfo: {
+        name: "flopay-node",
+        version: import_shared.SDK_VERSION
+      }
+    });
+    this.checkout = {
+      sessions: {
+        create: this.createSession.bind(this),
+        retrieve: this.retrieveSession.bind(this),
+        expire: this.expireSession.bind(this),
+        listLineItems: this.listLineItems.bind(this)
+      }
+    };
+    this.webhooks = {
+      constructEvent: this.constructWebhookEvent.bind(this)
+    };
+    this.customers = {
+      create: this.createCustomer.bind(this),
+      retrieve: this.retrieveCustomer.bind(this),
+      update: this.updateCustomer.bind(this)
+    };
+  }
+  /**
+   * Create a checkout session via the billing API.
+   *
+   * Mirrors `createCheckoutSession` from `clicktech-core-ui/modules`.
+   * Posts to `{billingApiUrl}/v1/checkouts/sessions` and returns
+   * the session UUID for redirect.
+   */
+  async createSession(params) {
+    const {
+      billingApiUrl,
+      checkoutBaseUrl,
+      items = [],
+      subscriptions = [],
+      account,
+      successUrl,
+      cancelUrl,
+      checkoutMode = "confirm",
+      couponCodes = [],
+      tagsData,
+      redirectParams = {},
+      timeoutMs = 12e3,
+      clientId,
+      utmMetadata
+    } = params;
+    const payload = {
+      clientId,
+      successUrl,
+      cancelUrl,
+      checkoutMode,
+      items: items.map((item) => ({
+        providerItemId: item.providerItemId,
+        providerItemName: item.providerItemName ?? null,
+        quantity: item.quantity ?? 1,
+        totalAmount: item.totalAmount,
+        overrideAmount: item.overrideAmount ?? null,
+        currency: item.currency ?? "USD"
+      })),
+      subscriptions: subscriptions.map((sub) => ({
+        providerPlanId: sub.providerPlanId,
+        providerPlanName: sub.providerPlanName ?? null,
+        quantity: sub.quantity ?? 1,
+        totalAmount: sub.totalAmount,
+        overrideAmount: sub.overrideAmount ?? null,
+        currency: sub.currency ?? "USD"
+      })),
+      accountData: {
+        userId: account.userId,
+        firstName: account.firstName ?? null,
+        lastName: account.lastName ?? null,
+        email: account.email,
+        country: account.country ?? null,
+        gender: account.gender ?? null,
+        city: account.city ?? null,
+        state: account.state ?? null,
+        zip: account.zip ?? null
+      },
+      couponCodes
+    };
+    if (tagsData) {
+      payload["tagsData"] = tagsData;
+    }
+    if (utmMetadata?.length) {
+      payload["utmMetadata"] = utmMetadata;
+    }
+    const url = `${billingApiUrl.replace(/\/+$/, "")}/v1/checkouts/sessions`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let status;
+    let body;
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+      status = response.status;
+      try {
+        body = await response.json();
+      } catch {
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+    if (status === 201) {
+      const uuid = body?.data?.uuid;
+      if (!uuid) {
+        throw new Error("Checkout session created but no UUID was returned by the billing API");
+      }
+      const redirectUrl = new URL(`${checkoutBaseUrl.replace(/\/+$/, "")}/secure`);
+      redirectUrl.searchParams.set("id", uuid);
+      for (const [key, value] of Object.entries(redirectParams)) {
+        redirectUrl.searchParams.set(key, value);
+      }
+      return { status: 201, redirectUrl: redirectUrl.toString() };
+    }
+    if (status === 204) {
+      return { status: 204 };
+    }
+    return { status };
+  }
+  normalizeStripeSession(session) {
+    const statusMap = {
+      open: "open",
+      complete: "complete",
+      expired: "expired"
+    };
+    return {
+      id: session.id,
+      clientSecret: session.client_secret ?? "",
+      mode: session.mode,
+      status: statusMap[session.status ?? "open"] ?? "open",
+      amount: session.amount_total ?? 0,
+      currency: session.currency ?? "usd",
+      metadata: session.metadata ?? {}
+    };
+  }
+  async retrieveSession(id) {
+    const session = await this.stripe.checkout.sessions.retrieve(id);
+    return this.normalizeStripeSession(session);
+  }
+  async expireSession(id) {
+    const session = await this.stripe.checkout.sessions.expire(id);
+    return this.normalizeStripeSession(session);
+  }
+  async listLineItems(id) {
+    const items = await this.stripe.checkout.sessions.listLineItems(id);
+    return items.data.map((item) => ({
+      price: item.price?.id,
+      quantity: item.quantity ?? 1
+    }));
+  }
+  constructWebhookEvent(payload, signature, secret) {
+    const event = this.stripe.webhooks.constructEvent(payload, signature, secret);
+    return {
+      id: event.id,
+      type: event.type,
+      data: event.data,
+      created: event.created
+    };
+  }
+  async createCustomer(params) {
+    const customer = await this.stripe.customers.create({
+      email: params.email,
+      name: params.name,
+      metadata: params.metadata
+    });
+    return {
+      id: customer.id,
+      email: customer.email ?? params.email,
+      firstName: params.name?.split(" ")[0],
+      lastName: params.name?.split(" ").slice(1).join(" ")
+    };
+  }
+  async retrieveCustomer(id) {
+    const customer = await this.stripe.customers.retrieve(id);
+    if (customer.deleted) {
+      throw new import_shared.FloPayError(
+        `Customer ${id} has been deleted`,
+        "api_error",
+        { code: "resource_missing" }
+      );
+    }
+    return {
+      id: customer.id,
+      email: customer.email ?? "",
+      firstName: customer.name?.split(" ")[0],
+      lastName: customer.name?.split(" ").slice(1).join(" ")
+    };
+  }
+  async updateCustomer(id, params) {
+    const customer = await this.stripe.customers.update(id, {
+      email: params.email,
+      name: params.name,
+      metadata: params.metadata
+    });
+    return {
+      id: customer.id,
+      email: customer.email ?? "",
+      firstName: customer.name?.split(" ")[0],
+      lastName: customer.name?.split(" ").slice(1).join(" ")
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FloPay
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/flopay-node.ts"],"sourcesContent":["export { FloPay } from './flopay-node.js';\nexport type { FloPayNodeOptions } from './flopay-node.js';\n","import Stripe from 'stripe';\nimport type {\n  CheckoutSession,\n  LineItem,\n  CreateSessionParams,\n  CheckoutSessionResult,\n  CreateCustomerParams,\n  UpdateCustomerParams,\n  WebhookEvent,\n  Customer,\n} from '@flopay/shared';\nimport { FloPayError, SDK_VERSION } from '@flopay/shared';\n\n/** Options for the FloPay Node SDK constructor. */\nexport interface FloPayNodeOptions {\n  apiVersion?: string;\n  /** Stripe secret key, required when using Stripe-specific operations. */\n  stripeSecretKey?: string;\n}\n\n/**\n * Server-side FloPay SDK.\n *\n * Supports two modes of operation:\n *\n * 1. **Billing API mode** — Creates checkout sessions via the FloPay/ClickTech\n *    billing API (`POST /v1/checkouts/sessions`). This mirrors the\n *    `createCheckoutSession` function from `clicktech-core-ui`.\n *\n * 2. **Stripe direct mode** — When a `stripeSecretKey` is provided, also\n *    exposes direct Stripe operations (customers, webhooks).\n *\n * @example\n * ```ts\n * import { FloPay } from '@flopay/node';\n *\n * const flopay = new FloPay('sk_test_...');\n *\n * // Create session via billing API\n * const result = await flopay.checkout.sessions.create({\n *   billingApiUrl: 'https://billing.example.com',\n *   checkoutBaseUrl: 'https://checkout.example.com',\n *   clientId: 'client_123',\n *   items: [{ providerItemId: 'prod_abc', totalAmount: 49.99 }],\n *   account: { userId: 'user_1', email: 'user@example.com' },\n *   successUrl: '/success',\n *   cancelUrl: '/cancel',\n * });\n * ```\n */\nexport class FloPay {\n  private readonly stripe: Stripe;\n\n  readonly checkout: {\n    sessions: {\n      /** Create a checkout session via the billing API. */\n      create: (params: CreateSessionParams) => Promise<CheckoutSessionResult>;\n      /** Retrieve a checkout session from Stripe. */\n      retrieve: (id: string) => Promise<CheckoutSession>;\n      /** Expire a checkout session on Stripe. */\n      expire: (id: string) => Promise<CheckoutSession>;\n      /** List line items for a Stripe checkout session. */\n      listLineItems: (id: string) => Promise<LineItem[]>;\n    };\n  };\n\n  readonly webhooks: {\n    constructEvent: (\n      payload: string | Buffer,\n      signature: string,\n      secret: string,\n    ) => WebhookEvent;\n  };\n\n  readonly customers: {\n    create: (params: CreateCustomerParams) => Promise<Customer>;\n    retrieve: (id: string) => Promise<Customer>;\n    update: (id: string, params: UpdateCustomerParams) => Promise<Customer>;\n  };\n\n  constructor(secretKey: string, options?: FloPayNodeOptions) {\n    if (!secretKey) {\n      throw new FloPayError(\n        'A secret key is required to initialize the FloPay server SDK.',\n        'authentication_error',\n      );\n    }\n\n    this.stripe = new Stripe(secretKey, {\n      apiVersion: '2025-04-30.basil' as Stripe.LatestApiVersion,\n      appInfo: {\n        name: 'flopay-node',\n        version: SDK_VERSION,\n      },\n    });\n\n    this.checkout = {\n      sessions: {\n        create: this.createSession.bind(this),\n        retrieve: this.retrieveSession.bind(this),\n        expire: this.expireSession.bind(this),\n        listLineItems: this.listLineItems.bind(this),\n      },\n    };\n\n    this.webhooks = {\n      constructEvent: this.constructWebhookEvent.bind(this),\n    };\n\n    this.customers = {\n      create: this.createCustomer.bind(this),\n      retrieve: this.retrieveCustomer.bind(this),\n      update: this.updateCustomer.bind(this),\n    };\n  }\n\n  /**\n   * Create a checkout session via the billing API.\n   *\n   * Mirrors `createCheckoutSession` from `clicktech-core-ui/modules`.\n   * Posts to `{billingApiUrl}/v1/checkouts/sessions` and returns\n   * the session UUID for redirect.\n   */\n  private async createSession(\n    params: CreateSessionParams,\n  ): Promise<CheckoutSessionResult> {\n    const {\n      billingApiUrl,\n      checkoutBaseUrl,\n      items = [],\n      subscriptions = [],\n      account,\n      successUrl,\n      cancelUrl,\n      checkoutMode = 'confirm',\n      couponCodes = [],\n      tagsData,\n      redirectParams = {},\n      timeoutMs = 12000,\n      clientId,\n      utmMetadata,\n    } = params;\n\n    const payload: Record<string, unknown> = {\n      clientId,\n      successUrl,\n      cancelUrl,\n      checkoutMode,\n      items: items.map((item) => ({\n        providerItemId: item.providerItemId,\n        providerItemName: item.providerItemName ?? null,\n        quantity: item.quantity ?? 1,\n        totalAmount: item.totalAmount,\n        overrideAmount: item.overrideAmount ?? null,\n        currency: item.currency ?? 'USD',\n      })),\n      subscriptions: subscriptions.map((sub) => ({\n        providerPlanId: sub.providerPlanId,\n        providerPlanName: sub.providerPlanName ?? null,\n        quantity: sub.quantity ?? 1,\n        totalAmount: sub.totalAmount,\n        overrideAmount: sub.overrideAmount ?? null,\n        currency: sub.currency ?? 'USD',\n      })),\n      accountData: {\n        userId: account.userId,\n        firstName: account.firstName ?? null,\n        lastName: account.lastName ?? null,\n        email: account.email,\n        country: account.country ?? null,\n        gender: account.gender ?? null,\n        city: account.city ?? null,\n        state: account.state ?? null,\n        zip: account.zip ?? null,\n      },\n      couponCodes,\n    };\n\n    if (tagsData) {\n      payload['tagsData'] = tagsData;\n    }\n\n    if (utmMetadata?.length) {\n      payload['utmMetadata'] = utmMetadata;\n    }\n\n    const url = `${billingApiUrl.replace(/\\/+$/, '')}/v1/checkouts/sessions`;\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), timeoutMs);\n\n    let status: number;\n    let body: { data?: { uuid?: string } } | undefined;\n\n    try {\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify(payload),\n        signal: controller.signal,\n      });\n\n      status = response.status;\n\n      try {\n        body = await response.json() as { data?: { uuid?: string } };\n      } catch {\n        // 204 or empty body\n      }\n    } finally {\n      clearTimeout(timer);\n    }\n\n    if (status === 201) {\n      const uuid = body?.data?.uuid;\n\n      if (!uuid) {\n        throw new Error('Checkout session created but no UUID was returned by the billing API');\n      }\n\n      const redirectUrl = new URL(`${checkoutBaseUrl.replace(/\\/+$/, '')}/secure`);\n      redirectUrl.searchParams.set('id', uuid);\n\n      for (const [key, value] of Object.entries(redirectParams)) {\n        redirectUrl.searchParams.set(key, value);\n      }\n\n      return { status: 201, redirectUrl: redirectUrl.toString() };\n    }\n\n    if (status === 204) {\n      return { status: 204 };\n    }\n\n    return { status };\n  }\n\n  private normalizeStripeSession(\n    session: Stripe.Checkout.Session,\n  ): CheckoutSession {\n    const statusMap: Record<string, CheckoutSession['status']> = {\n      open: 'open',\n      complete: 'complete',\n      expired: 'expired',\n    };\n\n    return {\n      id: session.id,\n      clientSecret: session.client_secret ?? '',\n      mode: session.mode as CheckoutSession['mode'],\n      status: statusMap[session.status ?? 'open'] ?? 'open',\n      amount: session.amount_total ?? 0,\n      currency: session.currency ?? 'usd',\n      metadata: (session.metadata as Record<string, string>) ?? {},\n    };\n  }\n\n  private async retrieveSession(id: string): Promise<CheckoutSession> {\n    const session = await this.stripe.checkout.sessions.retrieve(id);\n    return this.normalizeStripeSession(session);\n  }\n\n  private async expireSession(id: string): Promise<CheckoutSession> {\n    const session = await this.stripe.checkout.sessions.expire(id);\n    return this.normalizeStripeSession(session);\n  }\n\n  private async listLineItems(id: string): Promise<LineItem[]> {\n    const items = await this.stripe.checkout.sessions.listLineItems(id);\n    return items.data.map((item) => ({\n      price: item.price?.id,\n      quantity: item.quantity ?? 1,\n    }));\n  }\n\n  private constructWebhookEvent(\n    payload: string | Buffer,\n    signature: string,\n    secret: string,\n  ): WebhookEvent {\n    const event = this.stripe.webhooks.constructEvent(payload, signature, secret);\n\n    return {\n      id: event.id,\n      type: event.type,\n      data: event.data as unknown as Record<string, unknown>,\n      created: event.created,\n    };\n  }\n\n  private async createCustomer(params: CreateCustomerParams): Promise<Customer> {\n    const customer = await this.stripe.customers.create({\n      email: params.email,\n      name: params.name,\n      metadata: params.metadata,\n    });\n\n    return {\n      id: customer.id,\n      email: customer.email ?? params.email,\n      firstName: params.name?.split(' ')[0],\n      lastName: params.name?.split(' ').slice(1).join(' '),\n    };\n  }\n\n  private async retrieveCustomer(id: string): Promise<Customer> {\n    const customer = await this.stripe.customers.retrieve(id);\n\n    if (customer.deleted) {\n      throw new FloPayError(\n        `Customer ${id} has been deleted`,\n        'api_error',\n        { code: 'resource_missing' },\n      );\n    }\n\n    return {\n      id: customer.id,\n      email: customer.email ?? '',\n      firstName: customer.name?.split(' ')[0],\n      lastName: customer.name?.split(' ').slice(1).join(' '),\n    };\n  }\n\n  private async updateCustomer(\n    id: string,\n    params: UpdateCustomerParams,\n  ): Promise<Customer> {\n    const customer = await this.stripe.customers.update(id, {\n      email: params.email,\n      name: params.name,\n      metadata: params.metadata,\n    });\n\n    return {\n      id: customer.id,\n      email: customer.email ?? '',\n      firstName: customer.name?.split(' ')[0],\n      lastName: customer.name?.split(' ').slice(1).join(' '),\n    };\n  }\n}\n"],"mappings":"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","names":["Stripe"]}

package/dist/index.d.cts

@@ -0,0 +1,80 @@
+import { CreateSessionParams, CheckoutSessionResult, CheckoutSession, LineItem, WebhookEvent, CreateCustomerParams, Customer, UpdateCustomerParams } from '@flopay/shared';
+
+/** Options for the FloPay Node SDK constructor. */
+interface FloPayNodeOptions {
+    apiVersion?: string;
+    /** Stripe secret key, required when using Stripe-specific operations. */
+    stripeSecretKey?: string;
+}
+/**
+ * Server-side FloPay SDK.
+ *
+ * Supports two modes of operation:
+ *
+ * 1. **Billing API mode** — Creates checkout sessions via the FloPay/ClickTech
+ *    billing API (`POST /v1/checkouts/sessions`). This mirrors the
+ *    `createCheckoutSession` function from `clicktech-core-ui`.
+ *
+ * 2. **Stripe direct mode** — When a `stripeSecretKey` is provided, also
+ *    exposes direct Stripe operations (customers, webhooks).
+ *
+ * @example
+ * ```ts
+ * import { FloPay } from '@flopay/node';
+ *
+ * const flopay = new FloPay('sk_test_...');
+ *
+ * // Create session via billing API
+ * const result = await flopay.checkout.sessions.create({
+ *   billingApiUrl: 'https://billing.example.com',
+ *   checkoutBaseUrl: 'https://checkout.example.com',
+ *   clientId: 'client_123',
+ *   items: [{ providerItemId: 'prod_abc', totalAmount: 49.99 }],
+ *   account: { userId: 'user_1', email: 'user@example.com' },
+ *   successUrl: '/success',
+ *   cancelUrl: '/cancel',
+ * });
+ * ```
+ */
+declare class FloPay {
+    private readonly stripe;
+    readonly checkout: {
+        sessions: {
+            /** Create a checkout session via the billing API. */
+            create: (params: CreateSessionParams) => Promise<CheckoutSessionResult>;
+            /** Retrieve a checkout session from Stripe. */
+            retrieve: (id: string) => Promise<CheckoutSession>;
+            /** Expire a checkout session on Stripe. */
+            expire: (id: string) => Promise<CheckoutSession>;
+            /** List line items for a Stripe checkout session. */
+            listLineItems: (id: string) => Promise<LineItem[]>;
+        };
+    };
+    readonly webhooks: {
+        constructEvent: (payload: string | Buffer, signature: string, secret: string) => WebhookEvent;
+    };
+    readonly customers: {
+        create: (params: CreateCustomerParams) => Promise<Customer>;
+        retrieve: (id: string) => Promise<Customer>;
+        update: (id: string, params: UpdateCustomerParams) => Promise<Customer>;
+    };
+    constructor(secretKey: string, options?: FloPayNodeOptions);
+    /**
+     * Create a checkout session via the billing API.
+     *
+     * Mirrors `createCheckoutSession` from `clicktech-core-ui/modules`.
+     * Posts to `{billingApiUrl}/v1/checkouts/sessions` and returns
+     * the session UUID for redirect.
+     */
+    private createSession;
+    private normalizeStripeSession;
+    private retrieveSession;
+    private expireSession;
+    private listLineItems;
+    private constructWebhookEvent;
+    private createCustomer;
+    private retrieveCustomer;
+    private updateCustomer;
+}
+
+export { FloPay, type FloPayNodeOptions };

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import { CreateSessionParams, CheckoutSessionResult, CheckoutSession, LineItem, WebhookEvent, CreateCustomerParams, Customer, UpdateCustomerParams } from '@flopay/shared';
+
+/** Options for the FloPay Node SDK constructor. */
+interface FloPayNodeOptions {
+    apiVersion?: string;
+    /** Stripe secret key, required when using Stripe-specific operations. */
+    stripeSecretKey?: string;
+}
+/**
+ * Server-side FloPay SDK.
+ *
+ * Supports two modes of operation:
+ *
+ * 1. **Billing API mode** — Creates checkout sessions via the FloPay/ClickTech
+ *    billing API (`POST /v1/checkouts/sessions`). This mirrors the
+ *    `createCheckoutSession` function from `clicktech-core-ui`.
+ *
+ * 2. **Stripe direct mode** — When a `stripeSecretKey` is provided, also
+ *    exposes direct Stripe operations (customers, webhooks).
+ *
+ * @example
+ * ```ts
+ * import { FloPay } from '@flopay/node';
+ *
+ * const flopay = new FloPay('sk_test_...');
+ *
+ * // Create session via billing API
+ * const result = await flopay.checkout.sessions.create({
+ *   billingApiUrl: 'https://billing.example.com',
+ *   checkoutBaseUrl: 'https://checkout.example.com',
+ *   clientId: 'client_123',
+ *   items: [{ providerItemId: 'prod_abc', totalAmount: 49.99 }],
+ *   account: { userId: 'user_1', email: 'user@example.com' },
+ *   successUrl: '/success',
+ *   cancelUrl: '/cancel',
+ * });
+ * ```
+ */
+declare class FloPay {
+    private readonly stripe;
+    readonly checkout: {
+        sessions: {
+            /** Create a checkout session via the billing API. */
+            create: (params: CreateSessionParams) => Promise<CheckoutSessionResult>;
+            /** Retrieve a checkout session from Stripe. */
+            retrieve: (id: string) => Promise<CheckoutSession>;
+            /** Expire a checkout session on Stripe. */
+            expire: (id: string) => Promise<CheckoutSession>;
+            /** List line items for a Stripe checkout session. */
+            listLineItems: (id: string) => Promise<LineItem[]>;
+        };
+    };
+    readonly webhooks: {
+        constructEvent: (payload: string | Buffer, signature: string, secret: string) => WebhookEvent;
+    };
+    readonly customers: {
+        create: (params: CreateCustomerParams) => Promise<Customer>;
+        retrieve: (id: string) => Promise<Customer>;
+        update: (id: string, params: UpdateCustomerParams) => Promise<Customer>;
+    };
+    constructor(secretKey: string, options?: FloPayNodeOptions);
+    /**
+     * Create a checkout session via the billing API.
+     *
+     * Mirrors `createCheckoutSession` from `clicktech-core-ui/modules`.
+     * Posts to `{billingApiUrl}/v1/checkouts/sessions` and returns
+     * the session UUID for redirect.
+     */
+    private createSession;
+    private normalizeStripeSession;
+    private retrieveSession;
+    private expireSession;
+    private listLineItems;
+    private constructWebhookEvent;
+    private createCustomer;
+    private retrieveCustomer;
+    private updateCustomer;
+}
+
+export { FloPay, type FloPayNodeOptions };

package/dist/index.mjs

@@ -0,0 +1,223 @@
+// src/flopay-node.ts
+import Stripe from "stripe";
+import { FloPayError, SDK_VERSION } from "@flopay/shared";
+var FloPay = class {
+  constructor(secretKey, options) {
+    if (!secretKey) {
+      throw new FloPayError(
+        "A secret key is required to initialize the FloPay server SDK.",
+        "authentication_error"
+      );
+    }
+    this.stripe = new Stripe(secretKey, {
+      apiVersion: "2025-04-30.basil",
+      appInfo: {
+        name: "flopay-node",
+        version: SDK_VERSION
+      }
+    });
+    this.checkout = {
+      sessions: {
+        create: this.createSession.bind(this),
+        retrieve: this.retrieveSession.bind(this),
+        expire: this.expireSession.bind(this),
+        listLineItems: this.listLineItems.bind(this)
+      }
+    };
+    this.webhooks = {
+      constructEvent: this.constructWebhookEvent.bind(this)
+    };
+    this.customers = {
+      create: this.createCustomer.bind(this),
+      retrieve: this.retrieveCustomer.bind(this),
+      update: this.updateCustomer.bind(this)
+    };
+  }
+  /**
+   * Create a checkout session via the billing API.
+   *
+   * Mirrors `createCheckoutSession` from `clicktech-core-ui/modules`.
+   * Posts to `{billingApiUrl}/v1/checkouts/sessions` and returns
+   * the session UUID for redirect.
+   */
+  async createSession(params) {
+    const {
+      billingApiUrl,
+      checkoutBaseUrl,
+      items = [],
+      subscriptions = [],
+      account,
+      successUrl,
+      cancelUrl,
+      checkoutMode = "confirm",
+      couponCodes = [],
+      tagsData,
+      redirectParams = {},
+      timeoutMs = 12e3,
+      clientId,
+      utmMetadata
+    } = params;
+    const payload = {
+      clientId,
+      successUrl,
+      cancelUrl,
+      checkoutMode,
+      items: items.map((item) => ({
+        providerItemId: item.providerItemId,
+        providerItemName: item.providerItemName ?? null,
+        quantity: item.quantity ?? 1,
+        totalAmount: item.totalAmount,
+        overrideAmount: item.overrideAmount ?? null,
+        currency: item.currency ?? "USD"
+      })),
+      subscriptions: subscriptions.map((sub) => ({
+        providerPlanId: sub.providerPlanId,
+        providerPlanName: sub.providerPlanName ?? null,
+        quantity: sub.quantity ?? 1,
+        totalAmount: sub.totalAmount,
+        overrideAmount: sub.overrideAmount ?? null,
+        currency: sub.currency ?? "USD"
+      })),
+      accountData: {
+        userId: account.userId,
+        firstName: account.firstName ?? null,
+        lastName: account.lastName ?? null,
+        email: account.email,
+        country: account.country ?? null,
+        gender: account.gender ?? null,
+        city: account.city ?? null,
+        state: account.state ?? null,
+        zip: account.zip ?? null
+      },
+      couponCodes
+    };
+    if (tagsData) {
+      payload["tagsData"] = tagsData;
+    }
+    if (utmMetadata?.length) {
+      payload["utmMetadata"] = utmMetadata;
+    }
+    const url = `${billingApiUrl.replace(/\/+$/, "")}/v1/checkouts/sessions`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let status;
+    let body;
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+      status = response.status;
+      try {
+        body = await response.json();
+      } catch {
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+    if (status === 201) {
+      const uuid = body?.data?.uuid;
+      if (!uuid) {
+        throw new Error("Checkout session created but no UUID was returned by the billing API");
+      }
+      const redirectUrl = new URL(`${checkoutBaseUrl.replace(/\/+$/, "")}/secure`);
+      redirectUrl.searchParams.set("id", uuid);
+      for (const [key, value] of Object.entries(redirectParams)) {
+        redirectUrl.searchParams.set(key, value);
+      }
+      return { status: 201, redirectUrl: redirectUrl.toString() };
+    }
+    if (status === 204) {
+      return { status: 204 };
+    }
+    return { status };
+  }
+  normalizeStripeSession(session) {
+    const statusMap = {
+      open: "open",
+      complete: "complete",
+      expired: "expired"
+    };
+    return {
+      id: session.id,
+      clientSecret: session.client_secret ?? "",
+      mode: session.mode,
+      status: statusMap[session.status ?? "open"] ?? "open",
+      amount: session.amount_total ?? 0,
+      currency: session.currency ?? "usd",
+      metadata: session.metadata ?? {}
+    };
+  }
+  async retrieveSession(id) {
+    const session = await this.stripe.checkout.sessions.retrieve(id);
+    return this.normalizeStripeSession(session);
+  }
+  async expireSession(id) {
+    const session = await this.stripe.checkout.sessions.expire(id);
+    return this.normalizeStripeSession(session);
+  }
+  async listLineItems(id) {
+    const items = await this.stripe.checkout.sessions.listLineItems(id);
+    return items.data.map((item) => ({
+      price: item.price?.id,
+      quantity: item.quantity ?? 1
+    }));
+  }
+  constructWebhookEvent(payload, signature, secret) {
+    const event = this.stripe.webhooks.constructEvent(payload, signature, secret);
+    return {
+      id: event.id,
+      type: event.type,
+      data: event.data,
+      created: event.created
+    };
+  }
+  async createCustomer(params) {
+    const customer = await this.stripe.customers.create({
+      email: params.email,
+      name: params.name,
+      metadata: params.metadata
+    });
+    return {
+      id: customer.id,
+      email: customer.email ?? params.email,
+      firstName: params.name?.split(" ")[0],
+      lastName: params.name?.split(" ").slice(1).join(" ")
+    };
+  }
+  async retrieveCustomer(id) {
+    const customer = await this.stripe.customers.retrieve(id);
+    if (customer.deleted) {
+      throw new FloPayError(
+        `Customer ${id} has been deleted`,
+        "api_error",
+        { code: "resource_missing" }
+      );
+    }
+    return {
+      id: customer.id,
+      email: customer.email ?? "",
+      firstName: customer.name?.split(" ")[0],
+      lastName: customer.name?.split(" ").slice(1).join(" ")
+    };
+  }
+  async updateCustomer(id, params) {
+    const customer = await this.stripe.customers.update(id, {
+      email: params.email,
+      name: params.name,
+      metadata: params.metadata
+    });
+    return {
+      id: customer.id,
+      email: customer.email ?? "",
+      firstName: customer.name?.split(" ")[0],
+      lastName: customer.name?.split(" ").slice(1).join(" ")
+    };
+  }
+};
+export {
+  FloPay
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/flopay-node.ts"],"sourcesContent":["import Stripe from 'stripe';\nimport type {\n  CheckoutSession,\n  LineItem,\n  CreateSessionParams,\n  CheckoutSessionResult,\n  CreateCustomerParams,\n  UpdateCustomerParams,\n  WebhookEvent,\n  Customer,\n} from '@flopay/shared';\nimport { FloPayError, SDK_VERSION } from '@flopay/shared';\n\n/** Options for the FloPay Node SDK constructor. */\nexport interface FloPayNodeOptions {\n  apiVersion?: string;\n  /** Stripe secret key, required when using Stripe-specific operations. */\n  stripeSecretKey?: string;\n}\n\n/**\n * Server-side FloPay SDK.\n *\n * Supports two modes of operation:\n *\n * 1. **Billing API mode** — Creates checkout sessions via the FloPay/ClickTech\n *    billing API (`POST /v1/checkouts/sessions`). This mirrors the\n *    `createCheckoutSession` function from `clicktech-core-ui`.\n *\n * 2. **Stripe direct mode** — When a `stripeSecretKey` is provided, also\n *    exposes direct Stripe operations (customers, webhooks).\n *\n * @example\n * ```ts\n * import { FloPay } from '@flopay/node';\n *\n * const flopay = new FloPay('sk_test_...');\n *\n * // Create session via billing API\n * const result = await flopay.checkout.sessions.create({\n *   billingApiUrl: 'https://billing.example.com',\n *   checkoutBaseUrl: 'https://checkout.example.com',\n *   clientId: 'client_123',\n *   items: [{ providerItemId: 'prod_abc', totalAmount: 49.99 }],\n *   account: { userId: 'user_1', email: 'user@example.com' },\n *   successUrl: '/success',\n *   cancelUrl: '/cancel',\n * });\n * ```\n */\nexport class FloPay {\n  private readonly stripe: Stripe;\n\n  readonly checkout: {\n    sessions: {\n      /** Create a checkout session via the billing API. */\n      create: (params: CreateSessionParams) => Promise<CheckoutSessionResult>;\n      /** Retrieve a checkout session from Stripe. */\n      retrieve: (id: string) => Promise<CheckoutSession>;\n      /** Expire a checkout session on Stripe. */\n      expire: (id: string) => Promise<CheckoutSession>;\n      /** List line items for a Stripe checkout session. */\n      listLineItems: (id: string) => Promise<LineItem[]>;\n    };\n  };\n\n  readonly webhooks: {\n    constructEvent: (\n      payload: string | Buffer,\n      signature: string,\n      secret: string,\n    ) => WebhookEvent;\n  };\n\n  readonly customers: {\n    create: (params: CreateCustomerParams) => Promise<Customer>;\n    retrieve: (id: string) => Promise<Customer>;\n    update: (id: string, params: UpdateCustomerParams) => Promise<Customer>;\n  };\n\n  constructor(secretKey: string, options?: FloPayNodeOptions) {\n    if (!secretKey) {\n      throw new FloPayError(\n        'A secret key is required to initialize the FloPay server SDK.',\n        'authentication_error',\n      );\n    }\n\n    this.stripe = new Stripe(secretKey, {\n      apiVersion: '2025-04-30.basil' as Stripe.LatestApiVersion,\n      appInfo: {\n        name: 'flopay-node',\n        version: SDK_VERSION,\n      },\n    });\n\n    this.checkout = {\n      sessions: {\n        create: this.createSession.bind(this),\n        retrieve: this.retrieveSession.bind(this),\n        expire: this.expireSession.bind(this),\n        listLineItems: this.listLineItems.bind(this),\n      },\n    };\n\n    this.webhooks = {\n      constructEvent: this.constructWebhookEvent.bind(this),\n    };\n\n    this.customers = {\n      create: this.createCustomer.bind(this),\n      retrieve: this.retrieveCustomer.bind(this),\n      update: this.updateCustomer.bind(this),\n    };\n  }\n\n  /**\n   * Create a checkout session via the billing API.\n   *\n   * Mirrors `createCheckoutSession` from `clicktech-core-ui/modules`.\n   * Posts to `{billingApiUrl}/v1/checkouts/sessions` and returns\n   * the session UUID for redirect.\n   */\n  private async createSession(\n    params: CreateSessionParams,\n  ): Promise<CheckoutSessionResult> {\n    const {\n      billingApiUrl,\n      checkoutBaseUrl,\n      items = [],\n      subscriptions = [],\n      account,\n      successUrl,\n      cancelUrl,\n      checkoutMode = 'confirm',\n      couponCodes = [],\n      tagsData,\n      redirectParams = {},\n      timeoutMs = 12000,\n      clientId,\n      utmMetadata,\n    } = params;\n\n    const payload: Record<string, unknown> = {\n      clientId,\n      successUrl,\n      cancelUrl,\n      checkoutMode,\n      items: items.map((item) => ({\n        providerItemId: item.providerItemId,\n        providerItemName: item.providerItemName ?? null,\n        quantity: item.quantity ?? 1,\n        totalAmount: item.totalAmount,\n        overrideAmount: item.overrideAmount ?? null,\n        currency: item.currency ?? 'USD',\n      })),\n      subscriptions: subscriptions.map((sub) => ({\n        providerPlanId: sub.providerPlanId,\n        providerPlanName: sub.providerPlanName ?? null,\n        quantity: sub.quantity ?? 1,\n        totalAmount: sub.totalAmount,\n        overrideAmount: sub.overrideAmount ?? null,\n        currency: sub.currency ?? 'USD',\n      })),\n      accountData: {\n        userId: account.userId,\n        firstName: account.firstName ?? null,\n        lastName: account.lastName ?? null,\n        email: account.email,\n        country: account.country ?? null,\n        gender: account.gender ?? null,\n        city: account.city ?? null,\n        state: account.state ?? null,\n        zip: account.zip ?? null,\n      },\n      couponCodes,\n    };\n\n    if (tagsData) {\n      payload['tagsData'] = tagsData;\n    }\n\n    if (utmMetadata?.length) {\n      payload['utmMetadata'] = utmMetadata;\n    }\n\n    const url = `${billingApiUrl.replace(/\\/+$/, '')}/v1/checkouts/sessions`;\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), timeoutMs);\n\n    let status: number;\n    let body: { data?: { uuid?: string } } | undefined;\n\n    try {\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify(payload),\n        signal: controller.signal,\n      });\n\n      status = response.status;\n\n      try {\n        body = await response.json() as { data?: { uuid?: string } };\n      } catch {\n        // 204 or empty body\n      }\n    } finally {\n      clearTimeout(timer);\n    }\n\n    if (status === 201) {\n      const uuid = body?.data?.uuid;\n\n      if (!uuid) {\n        throw new Error('Checkout session created but no UUID was returned by the billing API');\n      }\n\n      const redirectUrl = new URL(`${checkoutBaseUrl.replace(/\\/+$/, '')}/secure`);\n      redirectUrl.searchParams.set('id', uuid);\n\n      for (const [key, value] of Object.entries(redirectParams)) {\n        redirectUrl.searchParams.set(key, value);\n      }\n\n      return { status: 201, redirectUrl: redirectUrl.toString() };\n    }\n\n    if (status === 204) {\n      return { status: 204 };\n    }\n\n    return { status };\n  }\n\n  private normalizeStripeSession(\n    session: Stripe.Checkout.Session,\n  ): CheckoutSession {\n    const statusMap: Record<string, CheckoutSession['status']> = {\n      open: 'open',\n      complete: 'complete',\n      expired: 'expired',\n    };\n\n    return {\n      id: session.id,\n      clientSecret: session.client_secret ?? '',\n      mode: session.mode as CheckoutSession['mode'],\n      status: statusMap[session.status ?? 'open'] ?? 'open',\n      amount: session.amount_total ?? 0,\n      currency: session.currency ?? 'usd',\n      metadata: (session.metadata as Record<string, string>) ?? {},\n    };\n  }\n\n  private async retrieveSession(id: string): Promise<CheckoutSession> {\n    const session = await this.stripe.checkout.sessions.retrieve(id);\n    return this.normalizeStripeSession(session);\n  }\n\n  private async expireSession(id: string): Promise<CheckoutSession> {\n    const session = await this.stripe.checkout.sessions.expire(id);\n    return this.normalizeStripeSession(session);\n  }\n\n  private async listLineItems(id: string): Promise<LineItem[]> {\n    const items = await this.stripe.checkout.sessions.listLineItems(id);\n    return items.data.map((item) => ({\n      price: item.price?.id,\n      quantity: item.quantity ?? 1,\n    }));\n  }\n\n  private constructWebhookEvent(\n    payload: string | Buffer,\n    signature: string,\n    secret: string,\n  ): WebhookEvent {\n    const event = this.stripe.webhooks.constructEvent(payload, signature, secret);\n\n    return {\n      id: event.id,\n      type: event.type,\n      data: event.data as unknown as Record<string, unknown>,\n      created: event.created,\n    };\n  }\n\n  private async createCustomer(params: CreateCustomerParams): Promise<Customer> {\n    const customer = await this.stripe.customers.create({\n      email: params.email,\n      name: params.name,\n      metadata: params.metadata,\n    });\n\n    return {\n      id: customer.id,\n      email: customer.email ?? params.email,\n      firstName: params.name?.split(' ')[0],\n      lastName: params.name?.split(' ').slice(1).join(' '),\n    };\n  }\n\n  private async retrieveCustomer(id: string): Promise<Customer> {\n    const customer = await this.stripe.customers.retrieve(id);\n\n    if (customer.deleted) {\n      throw new FloPayError(\n        `Customer ${id} has been deleted`,\n        'api_error',\n        { code: 'resource_missing' },\n      );\n    }\n\n    return {\n      id: customer.id,\n      email: customer.email ?? '',\n      firstName: customer.name?.split(' ')[0],\n      lastName: customer.name?.split(' ').slice(1).join(' '),\n    };\n  }\n\n  private async updateCustomer(\n    id: string,\n    params: UpdateCustomerParams,\n  ): Promise<Customer> {\n    const customer = await this.stripe.customers.update(id, {\n      email: params.email,\n      name: params.name,\n      metadata: params.metadata,\n    });\n\n    return {\n      id: customer.id,\n      email: customer.email ?? '',\n      firstName: customer.name?.split(' ')[0],\n      lastName: customer.name?.split(' ').slice(1).join(' '),\n    };\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@flopay/node",
+  "version": "0.1.0",
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flopay/flopay.git",
+    "directory": "packages/node"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "stripe": "^17.0.0",
+    "@flopay/shared": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "tsup": "^8.3.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  }
+}