@tirdad/sdk 0.0.0-stage → 2.1.41

package/examples/complete.ts

@@ -0,0 +1,486 @@
+/**
+ * FlexPrice TypeScript SDK – Complete example
+ *
+ * Demonstrates: client init, customer CRUD, pagination, plan creation,
+ * subscription lifecycle, event ingestion (single + bulk), invoice listing,
+ * idempotency headers, per-request timeouts, and webhook handling.
+ *
+ * Prerequisites:
+ *   FLEXPRICE_API_KEY  – your API key
+ *   FLEXPRICE_API_HOST – optional, defaults to us.api.flexprice.io
+ */
+
+import { FlexPrice } from "@flexprice/sdk";
+import type {
+  Customer,
+  Subscription,
+  Invoice,
+  Plan,
+  CreateCustomerRequest,
+  UpdateCustomerRequest,
+  CreatePlanRequest,
+  CreateSubscriptionRequest,
+  CancelSubscriptionRequest,
+  IngestEventRequest,
+  BulkIngestEventRequest,
+  InvoiceFilter,
+  CustomerFilter,
+  ListCustomersResponse,
+  ListInvoicesResponse,
+} from "@flexprice/sdk";
+import { SDKError } from "@flexprice/sdk";
+
+// ── Client initialisation ─────────────────────────────────────────────────────
+
+const apiKey = process.env.FLEXPRICE_API_KEY;
+const apiHost = process.env.FLEXPRICE_API_HOST ?? "us.api.flexprice.io";
+
+if (!apiKey) {
+  console.error("FLEXPRICE_API_KEY is not set. Exiting.");
+  process.exit(1);
+}
+
+const serverURL = apiHost.startsWith("http") ? apiHost : `https://${apiHost}`;
+
+const flexprice = new FlexPrice({
+  serverURL,
+  apiKeyAuth: apiKey,
+});
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/** Generate a unique external ID so the example is re-runnable. */
+const externalId = (prefix: string): string => `${prefix}-${Date.now()}`;
+
+// ── createOrGetCustomer ───────────────────────────────────────────────────────
+
+/**
+ * Creates a new customer, handling a 409 Conflict gracefully by fetching the
+ * existing record instead.  Demonstrates idempotency key and optional chaining.
+ */
+async function createOrGetCustomer(): Promise<Customer> {
+  console.log("\n// ── Create customer ──────────────────────────────────────");
+
+  const customerExternalId = externalId("acme-corp");
+
+  const request: CreateCustomerRequest = {
+    externalId: customerExternalId,
+    name: "Acme Corp",
+    email: "billing@acme-corp.example.com",
+    addressLine1: "123 Commerce Street",
+    addressCity: "San Francisco",
+    addressState: "CA",
+    addressPostalCode: "94105",
+    addressCountry: "US",
+    metadata: {
+      salesforce_id: "0010X000abcdef",
+      tier: "enterprise",
+    },
+  };
+
+  try {
+    // Pass an idempotency key via a custom request header so that retrying the
+    // same network call never creates a duplicate customer.
+    const customer = await flexprice.customers.createCustomer(request, {
+      headers: { "Idempotency-Key": `create-customer-${customerExternalId}` },
+    });
+
+    console.log(
+      `Created customer  id=${customer.id}  email=${customer.email ?? "N/A"}`
+    );
+    return customer;
+  } catch (err) {
+    // A 409 means the external_id already exists – retrieve the existing record.
+    if (err instanceof SDKError && err.statusCode === 409) {
+      console.log("Customer already exists; fetching by external_id …");
+      const result: ListCustomersResponse =
+        await flexprice.customers.queryCustomer({
+          externalId: customerExternalId,
+          limit: 1,
+        });
+      const existing = result.items?.[0];
+      if (!existing) {
+        throw new Error(
+          `409 returned but customer with externalId=${customerExternalId} not found`
+        );
+      }
+      console.log(
+        `Fetched existing customer  id=${existing.id}  name=${existing.name ?? "N/A"}`
+      );
+      return existing;
+    }
+    throw err;
+  }
+}
+
+// ── updateCustomer ────────────────────────────────────────────────────────────
+
+async function updateCustomer(customerId: string): Promise<Customer> {
+  console.log("\n// ── Update customer ──────────────────────────────────────");
+
+  const update: UpdateCustomerRequest = {
+    metadata: {
+      salesforce_id: "0010X000abcdef",
+      tier: "enterprise",
+      onboarded: "true",
+    },
+  };
+
+  const updated = await flexprice.customers.updateCustomer(update, customerId);
+  console.log(
+    `Updated customer  id=${updated.id}  name=${updated.name ?? "N/A"}`
+  );
+  return updated;
+}
+
+// ── paginateCustomers ─────────────────────────────────────────────────────────
+
+/**
+ * Iterates through every customer page until all records have been visited.
+ * Uses the `pagination.total` field to decide when to stop.
+ */
+async function paginateCustomers(): Promise<void> {
+  console.log(
+    "\n// ── Paginate all customers ────────────────────────────────"
+  );
+
+  const PAGE_SIZE = 50;
+  let offset = 0;
+  let total: number | undefined;
+  let page = 1;
+
+  do {
+    const filter: CustomerFilter = {
+      limit: PAGE_SIZE,
+      offset,
+      order: "desc",
+    };
+
+    const response: ListCustomersResponse =
+      await flexprice.customers.queryCustomer(filter);
+
+    total = response.pagination?.total;
+    const items = response.items ?? [];
+
+    console.log(
+      `  Page ${page}: fetched ${items.length} customers` +
+        (total !== undefined ? `  (total=${total})` : "")
+    );
+
+    for (const c of items) {
+      console.log(`    • ${c.id}  ${c.email ?? "no-email"}`);
+    }
+
+    offset += items.length;
+    page++;
+
+    // Stop if we received fewer items than the page size (last page) or once
+    // we have consumed everything reported by the server.
+  } while (
+    (total === undefined || offset < total) &&
+    (response.items?.length ?? 0) === PAGE_SIZE
+  );
+}
+
+// ── createPlan ────────────────────────────────────────────────────────────────
+
+async function createPlan(): Promise<Plan> {
+  console.log("\n// ── Create plan ──────────────────────────────────────────");
+
+  const request: CreatePlanRequest = {
+    name: "Pro Plan",
+    description: "Usage-based plan for professional teams",
+    lookupKey: `pro-plan-${Date.now()}`,
+    metadata: {
+      internal_code: "PLAN_PRO_V1",
+    },
+  };
+
+  const plan = await flexprice.plans.createPlan(request);
+  console.log(`Created plan  id=${plan.id}  name=${plan.name}`);
+  return plan;
+}
+
+// ── createSubscription ────────────────────────────────────────────────────────
+
+async function createSubscription(
+  customerId: string,
+  planId: string
+): Promise<Subscription> {
+  console.log(
+    "\n// ── Create subscription ──────────────────────────────────"
+  );
+
+  const request: CreateSubscriptionRequest = {
+    customerId,
+    planId,
+    billingCadence: "RECURRING",
+    billingPeriod: "MONTHLY",
+    currency: "USD",
+    collectionMethod: "charge_automatically",
+    startDate: new Date(),
+    metadata: {
+      source: "ts_sdk_example",
+    },
+  };
+
+  // Per-request timeout – useful for operations that trigger async work on the
+  // server (e.g. proration calculations) and may take longer than the default.
+  const subscription = await flexprice.subscriptions.createSubscription(
+    request,
+    { timeoutMs: 15000 }
+  );
+
+  console.log(
+    `Created subscription  id=${subscription.id}` +
+      `  status=${subscription.subscriptionStatus ?? "unknown"}`
+  );
+  return subscription;
+}
+
+// ── ingestEvents ──────────────────────────────────────────────────────────────
+
+async function ingestEvents(externalCustomerId: string): Promise<void> {
+  console.log(
+    "\n// ── Ingest single event ──────────────────────────────────"
+  );
+
+  // Single event ingest (returns void on HTTP 202)
+  const singleEvent: IngestEventRequest = {
+    eventName: "api_request",
+    externalCustomerId,
+    eventId: `evt-single-${Date.now()}`,
+    timestamp: new Date().toISOString(),
+    source: "ts_sdk_example",
+    properties: {
+      endpoint: "/v1/completions",
+      model: "gpt-4o",
+      tokens_used: "1500",
+    },
+  };
+
+  await flexprice.events.ingestEvent(singleEvent);
+  console.log("Single event accepted (202)");
+
+  // ── Bulk event ingest ───────────────────────────────────────────────────────
+  console.log(
+    "\n// ── Ingest events bulk ───────────────────────────────────"
+  );
+
+  const bulkPayload: BulkIngestEventRequest = {
+    events: [
+      {
+        eventName: "api_request",
+        externalCustomerId,
+        eventId: `evt-bulk-1-${Date.now()}`,
+        timestamp: new Date().toISOString(),
+        source: "ts_sdk_example",
+        properties: {
+          endpoint: "/v1/embeddings",
+          model: "text-embedding-3-small",
+          tokens_used: "800",
+        },
+      },
+      {
+        eventName: "storage_write",
+        externalCustomerId,
+        eventId: `evt-bulk-2-${Date.now()}`,
+        timestamp: new Date().toISOString(),
+        source: "ts_sdk_example",
+        properties: {
+          bucket: "user-uploads",
+          bytes_written: "204800",
+        },
+      },
+      {
+        eventName: "storage_read",
+        externalCustomerId,
+        eventId: `evt-bulk-3-${Date.now()}`,
+        timestamp: new Date().toISOString(),
+        source: "ts_sdk_example",
+        properties: {
+          bucket: "user-uploads",
+          bytes_read: "102400",
+        },
+      },
+    ],
+  };
+
+  await flexprice.events.ingestEventsBulk(bulkPayload);
+  console.log(`Bulk ingest accepted (202)  count=${bulkPayload.events.length}`);
+}
+
+// ── cancelSubscription ────────────────────────────────────────────────────────
+
+async function cancelSubscription(subscriptionId: string): Promise<void> {
+  console.log(
+    "\n// ── Cancel subscription ──────────────────────────────────"
+  );
+
+  const request: CancelSubscriptionRequest = {
+    cancellationType: "end_of_period",
+    reason: "Customer requested cancellation via account settings",
+  };
+
+  const cancelled = await flexprice.subscriptions.cancelSubscription(
+    subscriptionId,
+    request
+  );
+
+  console.log(
+    `Subscription cancellation scheduled  id=${cancelled.id}` +
+      `  status=${cancelled.subscriptionStatus ?? "unknown"}`
+  );
+}
+
+// ── listInvoices ──────────────────────────────────────────────────────────────
+
+async function listInvoices(customerId: string): Promise<void> {
+  console.log("\n// ── List invoices ────────────────────────────────────────");
+
+  const filter: InvoiceFilter = {
+    customerId,
+    invoiceStatus: ["DRAFT", "FINALIZED"],
+    limit: 20,
+    offset: 0,
+    order: "desc",
+  };
+
+  const response: ListInvoicesResponse =
+    await flexprice.invoices.queryInvoice(filter);
+
+  const invoices: Invoice[] = response.items ?? [];
+  console.log(
+    `Found ${invoices.length} invoice(s)` +
+      (response.pagination?.total !== undefined
+        ? `  (total=${response.pagination.total})`
+        : "")
+  );
+
+  for (const inv of invoices) {
+    console.log(
+      `  • ${inv.id}` +
+        `  status=${inv.invoiceStatus ?? "unknown"}` +
+        `  amount_due=${inv.amountDue ?? "0"} ${inv.currency ?? ""}`
+    );
+  }
+}
+
+// ── handleWebhook ─────────────────────────────────────────────────────────────
+
+/**
+ * Express-style webhook handler that reads the FlexPrice event type and
+ * type-narrows the payload.  Mount with:
+ *
+ *   app.post("/webhooks/flexprice", express.raw({ type: "*\/*" }), handleWebhook);
+ */
+async function handleWebhook(
+  req: { body: Buffer | string; headers: Record<string, string | string[] | undefined> },
+  res: { status: (code: number) => { send: (body: string) => void } }
+): Promise<void> {
+  const rawBody =
+    req.body instanceof Buffer ? req.body.toString("utf8") : req.body;
+
+  let event: Record<string, unknown>;
+  try {
+    event = JSON.parse(rawBody) as Record<string, unknown>;
+  } catch {
+    res.status(400).send("Invalid JSON");
+    return;
+  }
+
+  const eventType = event["event_type"] as string | undefined;
+
+  switch (eventType) {
+    case "invoice.created": {
+      const invoice = event["data"] as Invoice;
+      console.log(
+        `Webhook: invoice created  id=${invoice?.id}` +
+          `  amount_due=${invoice?.amountDue ?? "0"}`
+      );
+      break;
+    }
+
+    case "invoice.finalized": {
+      const invoice = event["data"] as Invoice;
+      console.log(
+        `Webhook: invoice finalised  id=${invoice?.id}` +
+          `  status=${invoice?.invoiceStatus ?? "unknown"}`
+      );
+      break;
+    }
+
+    case "subscription.created":
+    case "subscription.updated":
+    case "subscription.cancelled": {
+      const sub = event["data"] as Subscription;
+      console.log(
+        `Webhook: ${eventType}  id=${sub?.id}` +
+          `  status=${sub?.subscriptionStatus ?? "unknown"}`
+      );
+      break;
+    }
+
+    default:
+      console.log(`Webhook: unhandled event_type="${eventType ?? ""}"`);
+  }
+
+  res.status(200).send("OK");
+}
+
+// ── main ──────────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  console.log("FlexPrice TypeScript SDK – complete example");
+  console.log(`Server: ${serverURL}\n`);
+
+  // 1. Customer lifecycle
+  const customer = await createOrGetCustomer();
+  await updateCustomer(customer.id);
+
+  // 2. Pagination
+  await paginateCustomers();
+
+  // 3. Plan
+  const plan = await createPlan();
+
+  // 4. Subscription (requires a plan with at least one price; this example
+  //    assumes the plan already has prices attached via the dashboard / API)
+  const subscription = await createSubscription(customer.id, plan.id);
+
+  // 5. Usage events
+  const extId = customer.externalId ?? customer.id;
+  await ingestEvents(extId);
+
+  // 6. Invoices
+  await listInvoices(customer.id);
+
+  // 7. Cancel at end of current billing period
+  await cancelSubscription(subscription.id);
+
+  // 8. Webhook handler – simulated invocation (would normally be wired into
+  //    an HTTP server; shown here to demonstrate the typing pattern)
+  console.log("\n// ── Webhook handler (simulated) ──────────────────────────");
+  await handleWebhook(
+    {
+      body: JSON.stringify({
+        event_type: "invoice.created",
+        data: { id: "inv_demo", amountDue: "49.00", currency: "USD" },
+      }),
+      headers: { "content-type": "application/json" },
+    },
+    {
+      status: (code: number) => ({
+        send: (body: string) =>
+          console.log(`  Webhook response: ${code} ${body}`),
+      }),
+    }
+  );
+
+  console.log("\nAll examples completed successfully.");
+}
+
+main().catch((err: unknown) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/examples/quick-start.ts

@@ -0,0 +1,46 @@
+/**
+ * FlexPrice TypeScript SDK – Quick start example
+ *
+ * Default base URL: https://us.api.flexprice.io/v1
+ * Override with FLEXPRICE_API_HOST (full URL). Set FLEXPRICE_API_KEY in .env or environment.
+ */
+
+import { FlexPrice } from "@flexprice/sdk";
+
+const apiKey = process.env.FLEXPRICE_API_KEY;
+const serverURL =
+  process.env.FLEXPRICE_API_HOST ?? "https://us.api.flexprice.io/v1";
+
+if (!apiKey) {
+  console.error("Set FLEXPRICE_API_KEY in .env or environment");
+  process.exit(1);
+}
+
+const flexPrice = new FlexPrice({
+  serverURL,
+  apiKeyAuth: apiKey,
+});
+
+async function main() {
+  const customerId = `sample-customer-${Date.now()}`;
+
+  const customer = await flexPrice.customers.createCustomer({
+    externalId: customerId,
+    email: "user@example.com",
+    name: "Example Customer",
+  });
+  console.log("Customer:", customer);
+
+  const eventResult = await flexPrice.events.ingestEvent({
+    eventName: "Sample Event",
+    externalCustomerId: customerId,
+    properties: { source: "ts_sdk", environment: "test" },
+    source: "ts_sdk",
+  });
+  console.log("Event ingested:", eventResult);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/jsr.json

@@ -0,0 +1,25 @@
+
+
+{
+  "name": "@tirdad/sdk",
+  "version": "2.1.41",
+  "exports": {
+    ".": "./src/index.ts",    
+    "./sdk/models": "./src/sdk/models/index.ts",
+    "./lib/config": "./src/lib/config.ts",
+    "./lib/http": "./src/lib/http.ts",
+    "./lib/retries": "./src/lib/retries.ts",
+    "./lib/sdks": "./src/lib/sdks.ts",
+    "./types": "./src/types/index.ts"
+  },
+  "publish": {
+    "include": [
+      "LICENSE",
+      "README.md",
+      "RUNTIMES.md",
+      "USAGE.md",
+      "jsr.json",
+      "src/**/*.ts"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@tirdad/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.1.41",
+  "author": "Tirdad",
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./esm/index.d.ts",
+      "default": "./esm/index.js"
+    },
+    "./package.json": "./package.json",
+    "./types": {
+      "source": "./src/types/index.ts",
+      "types": "./esm/types/index.d.ts",
+      "default": "./esm/types/index.js"
+    },
+    "./sdk/models": {
+      "source": "./src/sdk/models/index.ts",
+      "types": "./esm/sdk/models/index.d.ts",
+      "default": "./esm/sdk/models/index.js"
+    },
+    "./*.js": {
+      "source": "./src/*.ts",
+      "types": "./esm/*.d.ts",
+      "default": "./esm/*.js"
+    },
+    "./*": {
+      "source": "./src/*.ts",
+      "types": "./esm/*.d.ts",
+      "default": "./esm/*.js"
+    }
+  },
+  "sideEffects": false,
+  "type": "module",
+  "main": "./esm/index.js",
+  "scripts": {
+    "lint": "oxlint --max-warnings=0 --deny-warnings --no-error-on-unmatched-pattern src",
+    "build": "tsgo",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260302.1",
+    "oxlint": "^1.60.0",
+    "typescript": "~5.8.3"
+  },
+  "dependencies": {
+    "zod": "^3.25.65 || ^4.0.0"
+  }
+}

package/src/core.ts

@@ -0,0 +1,13 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { ClientSDK } from "./lib/sdks.js";
+
+/**
+ * A minimal client to use when calling standalone SDK functions. Typically, an
+ * instance of this class would be instantiated once at the start of an
+ * application and passed around through some dependency injection mechanism  to
+ * parts of an application that need to make SDK calls.
+ */
+export class TirdadCore extends ClientSDK {}