@clocknext/sdk 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clocknext/sdk",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Official ClockNext SDK — record usage signals and manage plans, purchases, invoices, customers, and billing from your backend.",
   "license": "MIT",
   "type": "module",

package/src/client.ts

@@ -12,6 +12,7 @@ import { Portal } from "./resources/portal.js";
 import { Purchases } from "./resources/purchases.js";
 import { Signals } from "./resources/signals.js";
 import { Units } from "./resources/units.js";
+import { Taxes } from "./resources/taxes.js";
 import type { ClockNextConfig, ResolvedConfig } from "./types.js";
 
 /**
@@ -46,6 +47,8 @@ export class ClockNext {
   readonly units: Units;
   /** Composites: list, get, create, update, archive, unarchive (no delete). */
   readonly composites: Composites;
+  /** Tax rates by country: list, get, create, update (archive in the dashboard). */
+  readonly taxes: Taxes;
   /** Subscribe customers to plans (purchases). */
   readonly purchases: Purchases;
   /** Read invoices and mint hosted pay links. */
@@ -76,6 +79,7 @@ export class ClockNext {
     this.outcomes = new Outcomes(transport);
     this.units = new Units(transport);
     this.composites = new Composites(transport);
+    this.taxes = new Taxes(transport);
     this.purchases = new Purchases(transport);
     this.invoices = new Invoices(transport);
     this.payments = new Payments(transport);

package/src/index.ts

@@ -56,7 +56,6 @@ export type {
   CompositeCompletionInput,
   CompositeCompletionResult,
   SerializedUnitUsage,
-  UsageLogPeriod,
   UsageLogListParams,
   UsageLogAppliedRule,
   UsageLogOutcomeAttribution,
@@ -114,6 +113,11 @@ export type {
   Unit,
   CreateUnitInput,
   UpdateUnitInput,
+  // taxes
+  TaxBehavior,
+  Tax,
+  CreateTaxInput,
+  UpdateTaxInput,
   CompositeItem,
   Composite,
   CreateCompositeInput,

package/src/resources/signals.ts

@@ -436,7 +436,6 @@ export class Signals {
         customerId: params.customerId,
         limit: params.limit,
         cursor: params.cursor,
-        period: params.period,
         from: params.from,
         to: params.to,
       },

package/src/resources/taxes.ts

@@ -0,0 +1,59 @@
+import { activeQuery, filterByActive } from "../filters.js";
+import type { Transport } from "../http.js";
+import type { CreateTaxInput, Tax, UpdateTaxInput } from "../types.js";
+
+/**
+ * The `taxes` resource — the tax rates charged to customers by billing
+ * country (the same rates as Settings → Taxes). `/api/v1/taxes`.
+ *
+ * Every active tax for a customer's country is applied to their invoices and
+ * portal purchases automatically. There is no `delete()`, `archive()` or
+ * `unarchive()` — archiving and restoring a tax is done in the dashboard.
+ */
+export class Taxes {
+  constructor(private readonly transport: Transport) {}
+
+  /** List them, oldest first. `{ active: true }` returns only active ones,
+   *  `{ active: false }` only archived ones; omit it for both. */
+  async list(params: { active?: boolean } = {}): Promise<Tax[]> {
+    const res = await this.transport.request<{ taxes: Tax[] }>({
+      method: "GET",
+      path: "/api/v1/taxes",
+      query: { active: activeQuery(params.active) },
+    });
+    return filterByActive(res.taxes, params.active);
+  }
+
+  /** One tax. */
+  async get(id: string): Promise<Tax> {
+    const res = await this.transport.request<{ tax: Tax }>({
+      method: "GET",
+      path: `/api/v1/taxes/${encodeURIComponent(id)}`,
+    });
+    return res.tax;
+  }
+
+  /** Create one. It starts active. Two active taxes can't share a name
+   *  (ignoring case) in the same country — that's a `ConflictError`. Not
+   *  retried on failure — a retry could create a second row. */
+  async create(input: CreateTaxInput): Promise<Tax> {
+    const res = await this.transport.request<{ created: true; tax: Tax }>({
+      method: "POST",
+      path: "/api/v1/taxes",
+      body: input,
+    });
+    return res.tax;
+  }
+
+  /** PARTIAL update: only the fields you send change. Archived taxes can be
+   *  edited and stay archived. Only invoices issued afterwards use the new
+   *  values. */
+  async update(id: string, input: UpdateTaxInput): Promise<Tax> {
+    const res = await this.transport.request<{ updated: true; tax: Tax }>({
+      method: "PATCH",
+      path: `/api/v1/taxes/${encodeURIComponent(id)}`,
+      body: input,
+    });
+    return res.tax;
+  }
+}

package/src/types.ts

@@ -383,9 +383,6 @@ export interface TrackResult {
 // Usage log (mirrors GET /api/v1/signal/usage-log)
 // ---------------------------------------------------------------------------
 
-/** A preset time window, or `"custom"` for an explicit `from`/`to` range. */
-export type UsageLogPeriod = "all" | "today" | "7d" | "30d" | "90d" | "custom";
-
 export interface UsageLogListParams {
   customerId: string;
   /** Default 50, max 200. */
@@ -393,11 +390,11 @@ export interface UsageLogListParams {
   /** Pass back a previous page's `nextCursor` to fetch the next page. Omit for
    *  the first page. */
   cursor?: string;
-  /** Default `"all"`. Pair `"custom"` with `from`/`to`. */
-  period?: UsageLogPeriod;
-  /** `YYYY-MM-DD`, only used when `period` is `"custom"`. */
+  /** First day to include, `YYYY-MM-DD` (UTC). The whole day is included.
+   *  Keep sending the same value while paging with `cursor`. */
   from?: string;
-  /** `YYYY-MM-DD`, only used when `period` is `"custom"`. */
+  /** Last day to include, `YYYY-MM-DD` (UTC). The whole day is included.
+   *  Must not be before `from`. */
   to?: string;
 }
 
@@ -426,13 +423,14 @@ export interface UsageLogOutcomeAttribution {
  * One row of a customer's usage history, merged from every meter kind
  * (`UsageLog`, `UnitUsageLog`, completed composite occurrences) into one
  * feed and sorted by time — the same rows the customer portal's own "Usage
- * logs" table shows. `model`, `credit`, `outcome`, `unit` and `composite` are
- * each `null` unless `kind` matches that group.
+ * logs" table shows. `credit`, `outcome`, `unit` and `composite` are each
+ * `null` unless `type` matches that group.
  */
 export interface UsageLogEntry {
   id: string;
   createdAt: string;
-  kind: "credit" | "outcome" | "unit" | "wallet" | "composite";
+  /** Which meter this row is. */
+  type: "credit" | "outcome" | "unit" | "wallet" | "composite";
   status: SignalStatus;
   typeName: string | null;
   member: string | null;
@@ -447,16 +445,19 @@ export interface UsageLogEntry {
   };
   /** Formatted USD strings (e.g. `"$0.0064"`). */
   cost: { providedCost: string; customerCost: string };
-  /** Populated only when `kind === "credit"`. `amount` is a formatted credit
+  /** Populated only when `type === "credit"`. `amount` is a formatted credit
    *  value, honouring the org's credit-decimals display setting. */
   credit: { amount: string; appliedRules: UsageLogAppliedRule[] } | null;
-  /** Populated only when `kind === "outcome"`. */
+  /** Populated only when `type === "outcome"`. */
   outcome: UsageLogOutcomeAttribution | null;
-  /** Populated only when `kind === "unit"`. `quantity` is formatted. */
+  /** Populated only when `type === "unit"`. `quantity` is formatted. */
   unit: { quantity: string } | null;
-  /** Populated only when `kind === "composite"`. `amount` is a formatted USD
+  /** Populated only when `type === "composite"`. `amount` is a formatted USD
    *  price — the composite's flat price, read live, not stored per row. */
   composite: { amount: string } | null;
+  /** The `custom` object sent on the signal, as sent. `null` when none was
+   *  sent, and always `null` for unit and composite rows. */
+  custom: Record<string, unknown> | null;
 }
 
 export interface UsageLogPage {
@@ -963,6 +964,46 @@ export interface CreateUnitInput {
 /** `units.update()` body — PARTIAL. `tiers`, when sent, is the complete list. */
 export type UpdateUnitInput = Partial<CreateUnitInput>;
 
+/** How a tax applies: `"inclusive"` — already inside the price;
+ *  `"exclusive"` — added on top. Lower case only. */
+export type TaxBehavior = "inclusive" | "exclusive";
+
+/** A tax rate, charged to customers whose billing country matches. */
+export interface Tax {
+  id: string;
+  /** Shown on invoices. Unique among active taxes in the same country,
+   *  ignoring case. */
+  name: string;
+  /** A note for your team; not shown to customers. */
+  description: string | null;
+  /** 0–100. */
+  percentage: number;
+  /** ISO 3166-1 alpha-2, upper case (e.g. `"IN"`). */
+  countryCode: string;
+  behavior: TaxBehavior;
+  /** `false` once archived in the dashboard (Settings → Taxes): it no longer
+   *  applies to new invoices. */
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** `taxes.create()` body. */
+export interface CreateTaxInput {
+  /** 1–100 characters. */
+  name: string;
+  /** 0–100. */
+  percentage: number;
+  /** ISO 3166-1 alpha-2 (lower case is accepted). A country name is refused. */
+  countryCode: string;
+  behavior: TaxBehavior;
+  /** Up to 500 characters. */
+  description?: string | null;
+}
+
+/** `taxes.update()` body — PARTIAL: only the fields you send change. */
+export type UpdateTaxInput = Partial<CreateTaxInput>;
+
 /** A catalogue item a composite wraps. */
 export interface CompositeItem {
   id: string;