@billkit-eu/sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,103 @@
+/**
+ * Official Node.js / TypeScript SDK for BillKit.
+ *
+ * Quick start:
+ *
+ * ```ts
+ * import { BillKit } from "@billkit-eu/sdk";
+ *
+ * const client = new BillKit({ apiKey: "sk_test_..." });
+ * const customer = await client.customers.create<{ id: string }>({
+ *   email: "ada@example.com",
+ * });
+ * const product = await client.products.create<{ id: string }>({ name: "Pro" });
+ * const price = await client.prices.create<{ id: string }>({
+ *   product_id: product.id,
+ *   amount_cents: 999,
+ *   currency: "EUR",
+ *   interval: "month",
+ * });
+ * ```
+ *
+ * Auto-pagination via async iteration:
+ *
+ * ```ts
+ * for await (const customer of client.customers.iter()) {
+ *   console.log(customer);
+ * }
+ * ```
+ *
+ * Webhook verification:
+ *
+ * ```ts
+ * try {
+ *   const event = await verifyWebhookSignature({
+ *     payload: rawBody,
+ *     signatureHeader: req.headers["billkit-signature"],
+ *     secret: process.env.BILLKIT_WEBHOOK_SECRET!,
+ *   });
+ * } catch (err) {
+ *   return new Response(null, { status: 400 });
+ * }
+ * ```
+ *
+ * Logging is off by default and never configures anything for you. Pass
+ * a logger to opt in:
+ *
+ * ```ts
+ * const client = new BillKit({ apiKey: "sk_test_...", logger: console });
+ * ```
+ *
+ * See {@link BillKitLogger} for what is logged and what is withheld
+ * (keys, bodies and query strings never reach it).
+ */
+
+export { BillKit, type BillKitOptions } from "./client.js";
+export {
+  APIConnectionError,
+  APIError,
+  AuthenticationError,
+  BillKitError,
+  ConflictError,
+  InvalidRequestError,
+  PermissionError,
+  RateLimitError,
+  ResourceMissingError,
+  ServerError,
+} from "./errors.js";
+export { NOOP_LOGGER, type BillKitLogger, type LogContext } from "./logging.js";
+export { paginate, type ListResponseEnvelope, type PaginateOptions } from "./pagination.js";
+export type {
+  AuditLogsListParams,
+  BaseListParams,
+  CreateBillingPortalSessionParams,
+  CreateCheckoutSessionParams,
+  CreateCouponParams,
+  CreateCustomerParams,
+  CreateOneShotPaymentParams,
+  CreatePriceParams,
+  CreateProductParams,
+  CreateRefundParams,
+  CreateTaxRateParams,
+  CreateWebhookEndpointParams,
+  EventsListParams,
+  IdempotencyOptions,
+  ListParams,
+  PricesListParams,
+  RotateProviderCredentialParams,
+  SetPortalBrandingParams,
+  UpdateCouponParams,
+  UpdateCustomerParams,
+  UpdateProductParams,
+  UpdateTaxRateParams,
+  UpdateWebhookEndpointParams,
+  ValidateCouponParams,
+} from "./resources.js";
+export { DEFAULT_RETRY_POLICY, type RetryPolicy } from "./retry.js";
+export { VERSION } from "./version.js";
+export {
+  DEFAULT_WEBHOOK_TOLERANCE_SECONDS,
+  type VerifyWebhookOptions,
+  WebhookVerificationError,
+  verifyWebhookSignature,
+} from "./webhooks.js";

package/src/logging.ts

@@ -0,0 +1,72 @@
+/**
+ * Opt-in logging for the BillKit SDK.
+ *
+ * A library has no business deciding where its host application's logs
+ * go, so this SDK ships no logger, no transport, and no destination. It
+ * accepts one from you and writes to a no-op until you do:
+ *
+ * ```ts
+ * const client = new BillKit({ logger: console });
+ * ```
+ *
+ * `console` satisfies {@link BillKitLogger} structurally, so that line
+ * works with no adapter. So does a pino/winston/bunyan child logger:
+ * their `debug(msg, ctx)` / `warn(msg, ctx)` signatures line up. If yours
+ * takes its arguments the other way round, wrap it:
+ *
+ * ```ts
+ * const logger = {
+ *   debug: (m, c) => myLogger.debug(c, m),
+ *   warn: (m, c) => myLogger.warn(c, m),
+ * };
+ * ```
+ *
+ * ## What gets logged
+ *
+ * - **debug**: one call per HTTP attempt and one per response, with
+ *   `method`, `url`, `attempt`, `status`, `durationMs`, and `requestId`
+ *   (quote that id to BillKit support).
+ * - **warn**: one call per retry, naming the reason and the delay before
+ *   the next attempt. A retry is a real anomaly worth surfacing without
+ *   being an error.
+ *
+ * ## What is deliberately never logged
+ *
+ * - The `Authorization` header or the API key, in any form.
+ * - Request and response **bodies**. They carry customer PII (emails,
+ *   names, addresses) and billing detail; a payments SDK that quietly
+ *   copies those into its user's log sink has manufactured a compliance
+ *   problem on their behalf.
+ * - The **query string**. List filters routinely carry values like
+ *   `email=ada@example.com`, so only the path is logged.
+ * - The **final failure**. Every exhausted call throws a typed
+ *   `BillKitError` carrying the status, request id and retry-after;
+ *   logging it here as well would produce a duplicate the caller never
+ *   asked for and cannot suppress from their own sink.
+ */
+
+/** Structured context attached to a log line. Never contains secrets. */
+export type LogContext = Record<string, unknown>;
+
+/**
+ * The minimum a logger must do for the SDK to use it. Deliberately two
+ * methods: the SDK has exactly two things to say, and a narrow interface
+ * is one almost every logger already satisfies without an adapter.
+ */
+export interface BillKitLogger {
+  debug(message: string, context?: LogContext): void;
+  warn(message: string, context?: LogContext): void;
+}
+
+/**
+ * The default. Discards everything, so the SDK is silent until a logger
+ * is supplied, and costs nothing when it isn't.
+ */
+export const NOOP_LOGGER: BillKitLogger = {
+  debug(): void {
+    /* intentionally empty */
+  },
+  warn(): void {
+    /* intentionally empty */
+  },
+};

package/src/pagination.ts

@@ -0,0 +1,77 @@
+/**
+ * Auto-pagination helper for list endpoints.
+ *
+ * The BillKit API returns Stripe-shape envelopes:
+ *
+ *     { "object": "list", "data": [...], "has_more": bool }
+ *
+ * Cursor pagination is forward-only via the last item's `id` as
+ * `starting_after`. `paginate` walks every page and yields each row.
+ * Callers consume it via `for await`:
+ *
+ *     for await (const customer of client.customers.iter()) {
+ *       ...
+ *     }
+ */
+
+import type { QueryValue } from "./transport.js";
+
+export interface ListResponseEnvelope<T = unknown> {
+  readonly data?: readonly T[];
+  readonly has_more?: boolean;
+}
+
+export interface PaginateOptions {
+  /** Maps to the API's `limit` parameter. `undefined` lets the
+   *  server pick its default (10 today). */
+  pageSize?: number | undefined;
+  /** Extra filters forwarded on every page (e.g. `type` on events,
+   *  `action` on audit logs). Values are pruned of `undefined` so
+   *  callers can spread their full options object in. */
+  filters?: Readonly<Record<string, QueryValue>>;
+}
+
+type ListFn<T> = (params: {
+  limit?: number | undefined;
+  starting_after?: string | undefined;
+  [key: string]: QueryValue;
+}) => Promise<ListResponseEnvelope<T>>;
+
+/**
+ * Walk every page of `listFn` and yield each row.
+ *
+ * Three terminators, in priority order:
+ *   1. `has_more=false`: the server's authoritative signal (common case).
+ *   2. Empty `data` with `has_more=true`: shouldn't happen per the API
+ *      contract, but if a future server bug or proxy misbehaviour
+ *      produced it the iterator would loop forever. Belt-and-suspenders.
+ *   3. The last row has no `id`, so there is no cursor to advance with. The schema
+ *      doesn't allow it today, but same defensive reasoning.
+ */
+export async function* paginate<T>(
+  listFn: ListFn<T>,
+  options: PaginateOptions = {},
+): AsyncIterableIterator<T> {
+  const { pageSize, filters } = options;
+  const cleanFilters: Record<string, QueryValue> = {};
+  if (filters) {
+    for (const [k, v] of Object.entries(filters)) {
+      if (v !== undefined) cleanFilters[k] = v;
+    }
+  }
+
+  let cursor: string | undefined;
+  for (;;) {
+    const page = await listFn({
+      ...cleanFilters,
+      limit: pageSize,
+      starting_after: cursor,
+    });
+    const items = page.data ?? [];
+    for (const item of items) yield item;
+    if (!page.has_more || items.length === 0) return;
+    const last = items[items.length - 1] as { id?: string } | undefined;
+    cursor = last?.id;
+    if (cursor === undefined) return;
+  }
+}