@clocknext/sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,596 @@
+'use strict';
+
+// src/config.ts
+var DEFAULT_BASE_URL = "https://app.clocknext.com";
+function num(value, fallback, min) {
+  return typeof value === "number" && Number.isFinite(value) && value >= min ? value : fallback;
+}
+function resolveConfig(config) {
+  if (!config.apiKey || typeof config.apiKey !== "string") {
+    throw new Error("ClockNext: `apiKey` is required.");
+  }
+  const fetchImpl = config.fetch ?? (typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : void 0);
+  if (!fetchImpl) {
+    throw new Error(
+      "ClockNext: no global `fetch` found. Use Node 18+, or pass a `fetch` implementation."
+    );
+  }
+  return {
+    apiKey: config.apiKey,
+    baseUrl: (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
+    mode: config.mode ?? "async",
+    timeoutMs: num(config.timeoutMs, 1e4, 1),
+    batch: {
+      maxSize: num(config.batch?.maxSize, 20, 1),
+      maxIntervalMs: num(config.batch?.maxIntervalMs, 2e3, 0),
+      maxConcurrency: num(config.batch?.maxConcurrency, 5, 1),
+      maxQueueSize: num(config.batch?.maxQueueSize, 1e4, 1)
+    },
+    retry: {
+      maxAttempts: num(config.retry?.maxAttempts, 5, 1),
+      baseDelayMs: num(config.retry?.baseDelayMs, 200, 0),
+      maxDelayMs: num(config.retry?.maxDelayMs, 1e4, 0)
+    },
+    fetch: fetchImpl,
+    logger: config.logger ?? {},
+    onError: config.onError,
+    onFlush: config.onFlush,
+    onRetry: config.onRetry,
+    onDrop: config.onDrop
+  };
+}
+
+// src/queue.ts
+var InMemoryQueue = class {
+  items = [];
+  push(item) {
+    this.items.push(item);
+  }
+  take(n) {
+    return this.items.splice(0, n);
+  }
+  size() {
+    return this.items.length;
+  }
+};
+
+// src/flusher.ts
+var Flusher = class {
+  constructor(transport, cfg) {
+    this.transport = transport;
+    this.cfg = cfg;
+  }
+  transport;
+  cfg;
+  queue = new InMemoryQueue();
+  timer = null;
+  draining = null;
+  closed = false;
+  /** Buffer one signal. Drops (with onDrop) when closed or the queue is full. */
+  enqueue(item) {
+    if (this.closed) {
+      this.cfg.onDrop?.(item.signal, "send_failed");
+      return;
+    }
+    if (this.queue.size() >= this.cfg.batch.maxQueueSize) {
+      this.cfg.logger.warn?.("[clocknext] queue full \u2014 dropping signal");
+      this.cfg.onDrop?.(item.signal, "queue_full");
+      return;
+    }
+    this.queue.push(item);
+    if (this.queue.size() >= this.cfg.batch.maxSize) void this.flush();
+    else this.arm();
+  }
+  /** Arm the interval timer if it isn't already running. */
+  arm() {
+    if (this.timer || this.closed) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.flush();
+    }, this.cfg.batch.maxIntervalMs);
+    this.timer.unref?.();
+  }
+  /**
+   * Send everything currently buffered. Overlapping calls share the single
+   * in-progress drain, so total in-flight sends never exceed `maxConcurrency`.
+   */
+  flush() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (!this.draining) {
+      this.draining = this.drain().finally(() => {
+        this.draining = null;
+      });
+    }
+    return this.draining;
+  }
+  /** Drain the buffer in concurrency-bounded waves until it's empty. */
+  async drain() {
+    let sent = 0;
+    while (this.queue.size() > 0) {
+      const wave = this.queue.take(this.cfg.batch.maxConcurrency);
+      const results = await Promise.all(wave.map((item) => this.send(item)));
+      sent += results.filter(Boolean).length;
+    }
+    if (sent > 0) this.cfg.onFlush?.(sent);
+  }
+  /** Send one item; never throws — failures surface via onError/onDrop. */
+  async send(item) {
+    try {
+      await this.transport.request({
+        method: "POST",
+        path: "/api/v1/usage",
+        body: item.body,
+        idempotencyKey: item.idempotencyKey
+      });
+      return true;
+    } catch (error) {
+      this.cfg.onError?.(error, item.signal);
+      this.cfg.onDrop?.(item.signal, "send_failed");
+      return false;
+    }
+  }
+  get size() {
+    return this.queue.size();
+  }
+  /** Flush remaining signals, then refuse further enqueues. */
+  async close() {
+    this.closed = true;
+    await this.flush();
+  }
+};
+
+// src/errors.ts
+var ClockNextError = class extends Error {
+  /** HTTP status, when the failure came from a server response. */
+  status;
+  /** The idempotency key of the offending signal, when applicable. */
+  idempotencyKey;
+  /** Whether the SDK considers this failure worth retrying. */
+  retryable;
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.status = opts.status;
+    this.idempotencyKey = opts.idempotencyKey;
+    this.retryable = opts.retryable ?? false;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthError = class extends ClockNextError {
+};
+var ValidationError = class extends ClockNextError {
+};
+var NotFoundError = class extends ClockNextError {
+};
+var PlanError = class extends ClockNextError {
+};
+var AllowanceError = class extends ClockNextError {
+};
+var ConflictError = class extends ClockNextError {
+};
+var RateLimitError = class extends ClockNextError {
+  retryAfterMs;
+  constructor(message, opts = {}) {
+    super(message, { status: 429, idempotencyKey: opts.idempotencyKey, retryable: true });
+    this.retryAfterMs = opts.retryAfterMs;
+  }
+};
+var ServerError = class extends ClockNextError {
+};
+var NetworkError = class extends ClockNextError {
+  constructor(message, opts = {}) {
+    super(message, { idempotencyKey: opts.idempotencyKey, retryable: true });
+  }
+};
+function errorFromResponse(status, message, idempotencyKey, retryAfterMs) {
+  const msg = message || `Request failed with status ${status}.`;
+  const opts = { status, idempotencyKey };
+  if (status === 400) return new ValidationError(msg, opts);
+  if (status === 401) return new AuthError(msg, opts);
+  if (status === 404) return new NotFoundError(msg, opts);
+  if (status === 409) return new ConflictError(msg, { ...opts, retryable: true });
+  if (status === 422) {
+    return /insufficient/i.test(msg) ? new AllowanceError(msg, opts) : new PlanError(msg, opts);
+  }
+  if (status === 429) return new RateLimitError(msg, { idempotencyKey, retryAfterMs });
+  if (status >= 500) return new ServerError(msg, { ...opts, retryable: true });
+  return new ClockNextError(msg, opts);
+}
+
+// src/retry.ts
+function isRetryable(error) {
+  return error instanceof ClockNextError && error.retryable;
+}
+function parseRetryAfter(headers) {
+  const ms = headers.get("retry-after-ms");
+  if (ms) {
+    const n = Number(ms);
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  const ra = headers.get("retry-after");
+  if (ra) {
+    const secs = Number(ra);
+    if (Number.isFinite(secs)) return Math.max(0, secs * 1e3);
+    const date = Date.parse(ra);
+    if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  }
+  return void 0;
+}
+function computeBackoff(attempt, opts, retryAfterMs, rand = Math.random) {
+  if (retryAfterMs != null) return Math.min(retryAfterMs, opts.maxDelayMs);
+  const raw = opts.baseDelayMs * Math.pow(2, Math.max(0, attempt - 1));
+  const capped = Math.min(raw, opts.maxDelayMs);
+  return Math.round(capped * (0.5 + rand() * 0.5));
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/http.ts
+var SDK_VERSION = "0.1.0";
+var Transport = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+  }
+  cfg;
+  async request(opts) {
+    const url = this.buildUrl(opts.path, opts.query);
+    const replaySafe = opts.method === "GET" || opts.method === "DELETE" || opts.idempotencyKey != null;
+    const maxAttempts = opts.retry === false || !replaySafe ? 1 : this.cfg.retry.maxAttempts;
+    let attempt = 0;
+    while (true) {
+      attempt++;
+      try {
+        return await this.once(url, opts);
+      } catch (error) {
+        const canRetry = attempt < maxAttempts && isRetryable(error);
+        if (!canRetry) throw error;
+        const retryAfterMs = error instanceof RateLimitError ? error.retryAfterMs : void 0;
+        const delayMs = computeBackoff(attempt, this.cfg.retry, retryAfterMs);
+        this.cfg.onRetry?.({ attempt, delayMs, error });
+        this.cfg.logger.debug?.(
+          `[clocknext] retry ${attempt}/${maxAttempts - 1} in ${delayMs}ms`,
+          error instanceof Error ? error.message : error
+        );
+        await sleep(delayMs);
+      }
+    }
+  }
+  /** One attempt: fetch + timeout + envelope/status handling. */
+  async once(url, opts) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.cfg.timeoutMs);
+    let res;
+    try {
+      res = await this.cfg.fetch(url, {
+        method: opts.method,
+        headers: this.headers(opts),
+        body: opts.body === void 0 ? void 0 : JSON.stringify(opts.body),
+        signal: controller.signal
+      });
+    } catch (err) {
+      const message2 = controller.signal.aborted ? `Request to ${opts.path} timed out after ${this.cfg.timeoutMs}ms.` : `Network error calling ${opts.path}: ${err instanceof Error ? err.message : String(err)}`;
+      throw new NetworkError(message2, { idempotencyKey: opts.idempotencyKey });
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    let json = void 0;
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+      }
+    }
+    const obj = json ?? {};
+    const isNew = typeof obj === "object" && obj !== null && "statusDetail" in obj;
+    if (isNew) {
+      const detail = obj.statusDetail;
+      if (res.ok && detail?.status === "SUCCESS") {
+        return obj.result ?? {};
+      }
+      const message2 = detail?.message ?? `Request failed with status ${res.status}.`;
+      throw errorFromResponse(
+        res.status,
+        message2,
+        opts.idempotencyKey,
+        parseRetryAfter(res.headers)
+      );
+    }
+    const envelope = obj;
+    if (res.ok && envelope.ok !== false) {
+      return envelope;
+    }
+    const message = envelope.error ?? text ?? `Request failed with status ${res.status}.`;
+    throw errorFromResponse(
+      res.status,
+      message,
+      opts.idempotencyKey,
+      parseRetryAfter(res.headers)
+    );
+  }
+  headers(opts) {
+    const h = {
+      Authorization: `Bearer ${this.cfg.apiKey}`,
+      "User-Agent": `clocknext-sdk-js/${SDK_VERSION}`
+    };
+    if (opts.body !== void 0) h["Content-Type"] = "application/json";
+    if (opts.idempotencyKey) h["Idempotency-Key"] = opts.idempotencyKey;
+    return h;
+  }
+  buildUrl(path, query) {
+    let url = `${this.cfg.baseUrl}${path}`;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== void 0 && v !== "") params.set(k, String(v));
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    return url;
+  }
+};
+
+// src/resources/customers.ts
+var Customers = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** Create a customer. `POST /api/v1/customers`. */
+  async create(input) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: "/api/v1/customers",
+      body: input
+    });
+    return res.customer;
+  }
+  /** List customers, most-recent first (cursor-paginated). `GET /api/v1/customers`. */
+  async list(params = {}) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: "/api/v1/customers",
+      query: { limit: params.limit, q: params.q, cursor: params.cursor }
+    });
+    return { customers: res.customers, nextCursor: res.nextCursor };
+  }
+  /**
+   * Async iterator over ALL customers, transparently following the cursor.
+   * `for await (const c of cnk.customers.iterate()) { … }`
+   */
+  async *iterate(params = {}) {
+    let cursor;
+    do {
+      const page = await this.list({ ...params, cursor });
+      for (const c of page.customers) yield c;
+      cursor = page.nextCursor ?? void 0;
+    } while (cursor);
+  }
+  /** Fetch one customer. `GET /api/v1/customers/:id`. */
+  async get(id) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: `/api/v1/customers/${encodeURIComponent(id)}`
+    });
+    return res.customer;
+  }
+  /** Update a customer (partial). `PATCH /api/v1/customers/:id`. */
+  async update(id, input) {
+    const res = await this.transport.request({
+      method: "PATCH",
+      path: `/api/v1/customers/${encodeURIComponent(id)}`,
+      body: input
+    });
+    return res.customer;
+  }
+  /** Delete a customer (members, invitations, usage logs cascade). */
+  async delete(id) {
+    await this.transport.request({
+      method: "DELETE",
+      path: `/api/v1/customers/${encodeURIComponent(id)}`
+    });
+  }
+  /** A customer's usage history. `GET /api/v1/customers/:id/usage`. */
+  async usage(id, params = {}) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/usage`,
+      query: { limit: params.limit }
+    });
+    return { customer: res.customer, totals: res.totals, logs: res.logs };
+  }
+  /** Wallet / credit / outcome / unit balances. `GET …/:id/balances`. */
+  balances(id) {
+    return this.transport.request({
+      method: "GET",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/balances`
+    });
+  }
+  /** The customer's current plan. `GET …/:id/plan`. */
+  plan(id) {
+    return this.transport.request({
+      method: "GET",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/plan`
+    });
+  }
+  /** Revenue / cost / profit / margin over a window. `GET …/:id/revenue`. */
+  revenue(id, params = {}) {
+    return this.transport.request({
+      method: "GET",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/revenue`,
+      query: { range: params.range }
+    });
+  }
+};
+
+// src/resources/portal.ts
+var Portal = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  async createToken(input) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: "/api/v1/portal/token",
+      body: {
+        customerId: input.customerId,
+        ttlSeconds: input.ttlSeconds,
+        memberEmail: input.memberEmail
+      }
+    });
+    return {
+      token: res.token,
+      expiresAt: res.expiresAt,
+      expiresIn: res.expiresIn
+    };
+  }
+};
+
+// src/idempotency.ts
+function newIdempotencyKey() {
+  const webcrypto = globalThis.crypto;
+  if (webcrypto?.randomUUID) return webcrypto.randomUUID();
+  const b = new Uint8Array(16);
+  if (webcrypto?.getRandomValues) {
+    webcrypto.getRandomValues(b);
+  } else {
+    for (let i = 0; i < 16; i++) b[i] = Math.floor(Math.random() * 256);
+  }
+  b[6] = b[6] & 15 | 64;
+  b[8] = b[8] & 63 | 128;
+  const hex = Array.from(b, (n) => n.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+// src/resources/signals.ts
+function signalToWire(signal) {
+  const body = {
+    customerId: signal.customerId,
+    type: signal.type,
+    model: signal.model
+  };
+  if (signal.member) body.member = signal.member;
+  if (signal.status) body.status = signal.status;
+  if (signal.custom) body.custom = signal.custom;
+  if (signal.idempotencyKey) body.idempotencyKey = signal.idempotencyKey;
+  const t = signal.tokens;
+  if (t) {
+    if (t.input != null) body.inputTokens = t.input;
+    if (t.output != null) body.outputTokens = t.output;
+    if (t.cache != null) body.cacheTokens = t.cache;
+  }
+  if (signal.type === "credit" || signal.type === "outcome") {
+    body.key = signal.key;
+  }
+  return body;
+}
+var Signals = class {
+  constructor(transport, flusher, cfg) {
+    this.transport = transport;
+    this.flusher = flusher;
+    this.cfg = cfg;
+  }
+  transport;
+  flusher;
+  cfg;
+  async track(signal, opts = {}) {
+    const idempotencyKey = signal.idempotencyKey ?? newIdempotencyKey();
+    const body = signalToWire({ ...signal, idempotencyKey });
+    const sendNow = opts.wait || this.cfg.mode === "sync";
+    if (!sendNow) {
+      this.flusher.enqueue({ body, idempotencyKey, signal });
+      return { idempotencyKey, queued: true };
+    }
+    const res = await this.transport.request({
+      method: "POST",
+      path: "/api/v1/usage",
+      body,
+      idempotencyKey
+    });
+    return {
+      idempotencyKey,
+      queued: false,
+      usageLog: res.usageLog ?? null
+    };
+  }
+  /** Meter a named credit. */
+  credit(input, opts) {
+    return this.track({ ...input, type: "credit" }, opts);
+  }
+  /** Debit the customer's wallet at model cost. */
+  wallet(input, opts) {
+    return this.track({ ...input, type: "wallet" }, opts);
+  }
+  /** Advance one step of an outcome workflow. */
+  outcome(input, opts) {
+    return this.track({ ...input, type: "outcome" }, opts);
+  }
+  /** Recent usage logs + totals for a customer. `GET /api/v1/usage`. */
+  async list(params) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: "/api/v1/usage",
+      query: { customerId: params.customerId, limit: params.limit }
+    });
+    return { customer: res.customer, totals: res.totals, logs: res.logs };
+  }
+};
+
+// src/client.ts
+var ClockNext = class {
+  /** Record + read usage signals. */
+  signals;
+  /** Manage customers and read their insights. */
+  customers;
+  /** Mint customer-portal embed tokens. */
+  portal;
+  cfg;
+  flusher;
+  constructor(config) {
+    this.cfg = resolveConfig(config);
+    if (typeof window !== "undefined") {
+      this.cfg.logger.warn?.(
+        "[clocknext] Running in a browser exposes your secret API key. Use this SDK only on a server/backend."
+      );
+    }
+    const transport = new Transport(this.cfg);
+    this.flusher = new Flusher(transport, this.cfg);
+    this.signals = new Signals(transport, this.flusher, this.cfg);
+    this.customers = new Customers(transport);
+    this.portal = new Portal(transport);
+  }
+  /** Number of signals currently buffered (async mode). */
+  get pending() {
+    return this.flusher.size;
+  }
+  /** Force-send all buffered signals now. Await before a serverless return. */
+  flush() {
+    return this.flusher.flush();
+  }
+  /** Flush and stop the background timer. Call on graceful shutdown. */
+  close() {
+    return this.flusher.close();
+  }
+};
+
+exports.AllowanceError = AllowanceError;
+exports.AuthError = AuthError;
+exports.ClockNext = ClockNext;
+exports.ClockNextError = ClockNextError;
+exports.ConflictError = ConflictError;
+exports.NetworkError = NetworkError;
+exports.NotFoundError = NotFoundError;
+exports.PlanError = PlanError;
+exports.RateLimitError = RateLimitError;
+exports.ServerError = ServerError;
+exports.ValidationError = ValidationError;
+exports.newIdempotencyKey = newIdempotencyKey;
+exports.signalToWire = signalToWire;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map