convex-weflayr 0.1.0 → 0.2.0

package/README.md

@@ -1,37 +1,42 @@
 # convex-weflayr
 
-A Convex component that sends your app's model calls through the
-[Weflayr](https://weflayr.com) gateway, and saves what each call cost, per
-customer, in your own database.
-
-Weflayr can show cost, run benchmarks and compare models, but only if every
-request says which feature, which call and which customer it belongs to. In a
-Convex app you would build that header by hand on every call, and the cost data
-would stay in Weflayr's dashboard, out of reach of your own code. This component
-adds the header for you and writes each call's usage into tables your app can
-query. So your app can act on cost: show a customer their usage, warn at 80% of
-a plan, stop at 100%.
-
-```mermaid
-flowchart LR
-  A["Convex action<br/>(your AI feature)"] -->|"1. model call + header<br/>feature, call, customer"| G["Weflayr gateway"]
-  G -->|"2. answer + usage"| A
-  A -->|"3. track() saves the call"| C[("convex-weflayr tables<br/>calls, daily totals, budgets")]
-  C -->|"4. cost per customer,<br/>call, feature, day"| Q["Your queries and UI"]
-  C -->|"5. assertWithinBudget()"| A
-```
+A Convex component for running your app on [Weflayr](https://weflayr.com)
+routing strategies, with every call tagged by the customer it serves. It also
+brings Weflayr's real cost and margin per customer back into your Convex
+database, so your app can show it and act on it.
+
+Weflayr is a gateway that decides which model answers each call. You benchmark
+your own calls on other models, save the result as a routing strategy, and your
+code sends `model: "strategy/<id>"`. Weflayr then picks the model per call, and
+its routing overrides can treat a customer differently by their cost or their
+margin. All of that depends on each call saying which customer, feature and call
+it belongs to. This component does that in a Convex action, and keeps what comes
+back where your queries can reach it.
+
+![How a call flows: your Convex action calls a strategy through the Weflayr gateway, the component saves the call, and sync brings Weflayr's cost and margin back](https://raw.githubusercontent.com/sholajegede/convex-weflayr/main/docs/images/flow.png)
 
 ## What you get
 
-- **Cost per customer.** Every call is saved with its customer, call name,
-  feature, plan, model, tokens, cost, latency and status. Totals by customer,
-  call, feature and day are one query away, and they update live in your UI.
-- **Budgets.** Give a customer a monthly dollar budget. Their next call is
-  stopped before the model runs, and other customers carry on.
-- **Agent runs.** Give every step of a run the same run id. You see what the run
-  cost, step by step, and you can stop it part way.
-- **Cheaper models, with proof.** Each call has a fixed name, so Weflayr can
-  replay your real calls on other models and score the answers.
+- **The customer on every call.** Read from your login or your own function.
+  Per-customer routing overrides, cost and margin in Weflayr all depend on it.
+  A call without a customer fails by default, so none go untagged.
+- **Strategies instead of model names.** `strategy("support", 3)` pins a version
+  in production and `strategy("support")` follows the latest. Changing which
+  model answers is a change in the Weflayr dashboard, not a deploy. Each call is
+  saved with the model the strategy picked.
+- **Revenue and plan into Weflayr.** Push revenue from any billing system and
+  tag customers with their plan, so margin and per-plan views work.
+- **Weflayr's cost and margin in your database.** `sync` saves each customer's
+  real cost, revenue, margin and risk status for the month. Show it in your UI
+  with a live query, and stop a customer whose margin status you list.
+- **Budgets.** A monthly dollar budget per customer, checked against that real
+  cost. The next call is stopped before the model runs, and other customers
+  carry on.
+- **Agent runs.** Every step of a run carries one feature run id, so Weflayr
+  prices the whole run. You can also read the run's cost step by step and stop
+  it part way.
+- **A per-call record.** Every call is saved with customer, call, feature, plan,
+  model, tokens, cost estimate, latency and status, for lists in your own UI.
 - **Calls that survive a gateway failure.** `withFallback()` can run the call
   direct if the gateway fails. This is optional.
 - **A Vercel AI SDK model** for the gateway, if you use the AI SDK.
@@ -69,23 +74,23 @@ Open the app and paste your key. Then:
 An agent run. Four steps share one run id, so the cost of the run is the sum of
 its steps:
 
-![An agent run with the cost of each step](docs/images/agent-run.jpg)
+![An agent run with the cost of each step](https://raw.githubusercontent.com/sholajegede/convex-weflayr/main/docs/images/agent-run.jpg)
 
 A budget. After three calls the customer has used $0.000021 of a $0.00002
 budget, and the fourth call is stopped before the model runs:
 
-![A customer stopped at their monthly budget](docs/images/budget-block.jpg)
+![A customer stopped at their monthly budget](https://raw.githubusercontent.com/sholajegede/convex-weflayr/main/docs/images/budget-block.jpg)
 
 Spend by customer and by call, and every saved call:
 
-![Spend by customer](docs/images/customers.jpg)
+![Spend by customer](https://raw.githubusercontent.com/sholajegede/convex-weflayr/main/docs/images/customers.jpg)
 
-![The call log](docs/images/calls.jpg)
+![The call log](https://raw.githubusercontent.com/sholajegede/convex-weflayr/main/docs/images/calls.jpg)
 
 The same calls in the Weflayr dashboard, grouped by the feature names the
 component sent:
 
-![Cost per feature in Weflayr](docs/images/weflayr-dashboard.jpg)
+![Cost per feature in Weflayr](https://raw.githubusercontent.com/sholajegede/convex-weflayr/main/docs/images/weflayr-dashboard.jpg)
 
 About your key: it is saved in your browser's localStorage and sent with each
 call so the call can be made. It is never saved in the database. Each browser
@@ -121,13 +126,18 @@ npx convex env set WEFLAYR_CUSTOMERS "*"
 `WEFLAYR_CUSTOMERS` is a comma separated list of customer ids, or `*` for all.
 When it is empty, no customer goes through the gateway.
 
+Give the key the Gateway scope for model calls, and the Management scope as well
+for cost, margin, revenue and tags. To use a separate management key, set
+`WEFLAYR_MANAGEMENT_KEY`.
+
 ## Use it
 
-Create one `Weflayr` instance. Name your calls and the feature each one belongs
-to. A benchmark in Weflayr is set up per call name, so keep the names stable.
+Create one `Weflayr` instance. Name your calls, the feature each belongs to, and
+the model or strategy each uses. A benchmark in Weflayr is set up per call name,
+so keep the names stable.
 
 ```ts
-import { Weflayr } from "convex-weflayr";
+import { Weflayr, strategy } from "convex-weflayr";
 import { components } from "./_generated/api";
 
 export const weflayr = new Weflayr(components.weflayr, {
@@ -136,37 +146,99 @@ export const weflayr = new Weflayr(components.weflayr, {
     "classify-ticket": "support-replies",
     "summarise-thread": "thread-summaries",
   },
-  // Dollars per million tokens, from your provider's price list.
+  // Pin a version in production, follow the latest elsewhere.
+  models: {
+    "draft-reply": strategy("support", process.env.NODE_ENV === "production" ? 4 : undefined),
+    "classify-ticket": "claude-haiku-5-5",
+  },
+  defaultModel: strategy("default"),
+  // Who the call is for. The default is the signed-in user's id.
+  customer: async (ctx) => (await ctx.auth.getUserIdentity())?.orgId as string | undefined,
+  // Stop a customer whose margin is in one of these states.
+  stopOnMargin: ["unprofitable"],
+  // Dollars per million tokens, for estimates between syncs.
   prices: {
     "claude-haiku-5-5": { inputPerMillion: 0.1, outputPerMillion: 0.5 },
   },
 });
 ```
 
-Call a model through the gateway with the AI SDK:
+Call the model through the gateway with the AI SDK. `callMeta` gives the
+customer and the model for the call:
 
 ```ts
 import { generateText } from "ai";
 import { weflayrModel } from "convex-weflayr/ai-sdk";
 
-const meta = { customer: workspace.name, plan: workspace.plan, call: "classify-ticket" };
+const meta = await weflayr.callMeta(ctx, { call: "draft-reply", plan: workspace.plan });
 
-const result = await weflayr.track(
-  ctx,
-  { ...meta, model: "claude-haiku-5-5" },
-  () =>
-    generateText({
-      model: weflayrModel(weflayr, "claude-haiku-5-5"),
-      headers: weflayr.headers(meta),
-      prompt,
-    }),
+const result = await weflayr.track(ctx, meta, () =>
+  generateText({
+    model: weflayrModel(weflayr, meta.model),
+    headers: weflayr.headers(meta),
+    prompt,
+  }),
 );
 ```
 
-`ctx` is any action context. `track` times the call and saves it. If the call
-fails, it saves the failure and throws the error again. Without the AI SDK,
-`weflayr.connection()` returns the base URL and key for any OpenAI compatible
-client.
+`ctx` is any action context. `track` times the call and saves it, with the model
+that answered when the model is a strategy. If the call fails, it saves the
+failure and throws the error again. When the gateway changed the request, for
+example by removing a setting the chosen model does not take, the warning is
+logged and saved with the call. Without the AI SDK, `weflayr.connection()`
+returns the base URL and key for any OpenAI compatible client.
+
+A call with no customer throws, so nothing reaches Weflayr untagged. To log a
+warning and send `unknown` instead, set `missingCustomer: "warn"`.
+
+### Push revenue and plan
+
+Weflayr computes margin from revenue. If you bill with Stripe, connect it in
+Weflayr and skip this. For any other billing system, push revenue from your
+billing webhook or a nightly job:
+
+```ts
+await weflayr.sendRevenue([
+  { customer_name: workspace.id, amount: 49, month: "2026-11", revenue_id: invoice.id },
+]);
+
+await weflayr.tagCustomers({ [workspace.id]: { plan: "pro" } });
+```
+
+Rows are sent as upserts keyed by `revenue_id`, so a retried webhook does not
+book the same invoice twice, and a temporary Weflayr error is retried. Use one
+revenue source per customer and month: Weflayr adds sources together.
+
+### Bring cost and margin back
+
+Run `sync` on a schedule. It reads each customer's cost, and margin when the
+project has revenue, for the month and saves them in the component:
+
+```ts
+// convex/crons.ts
+import { cronJobs } from "convex/server";
+import { internal } from "./_generated/api";
+
+const crons = cronJobs();
+crons.interval("sync weflayr", { minutes: 10 }, internal.billing.sync, {});
+export default crons;
+
+// convex/billing.ts
+export const sync = internalAction({
+  args: {},
+  handler: async (ctx) => await weflayr.sync(ctx),
+});
+```
+
+Then read it from a query, so your UI updates live:
+
+```ts
+const status = await weflayr.customerStatus(ctx, "acme");
+// { costUsd, revenue, marginPct, riskStatus, syncedAt } or null before the first sync
+```
+
+`riskStatus` is `healthy`, `watch`, `at_risk` or `unprofitable`. On a project
+without revenue the cost is saved and the margin fields are empty.
 
 ### Streaming
 
@@ -177,13 +249,12 @@ result only has its usage when the stream ends, so record the call yourself in
 ```ts
 const started = Date.now();
 const result = streamText({
-  model: weflayrModel(weflayr, "claude-haiku-5-5"),
+  model: weflayrModel(weflayr, meta.model),
   headers: weflayr.headers(meta),
   prompt,
   onFinish: async ({ usage }) => {
     await weflayr.record(ctx, {
       ...meta,
-      model: "claude-haiku-5-5",
       inputTokens: usage.inputTokens ?? 0,
       outputTokens: usage.outputTokens ?? 0,
       latencyMs: Date.now() - started,
@@ -202,10 +273,10 @@ your own provider key.
 ```ts
 const result = await weflayr.withFallback(
   ctx,
-  { ...meta, model },
+  meta,
   {
-    gateway: () => generateText({ model: weflayrModel(weflayr, model), headers: weflayr.headers(meta), prompt }),
-    direct: () => generateText({ model: yourProvider(model), prompt }),
+    gateway: () => generateText({ model: weflayrModel(weflayr, meta.model), headers: weflayr.headers(meta), prompt }),
+    direct: () => generateText({ model: yourProvider("claude-haiku-5-5"), prompt }),
   },
 );
 ```
@@ -217,9 +288,10 @@ saved.
 ### Group the calls of one job
 
 Pass the same `runId` (`newRunId()` makes one) to every call of one job. It is
-saved with each call and sent to Weflayr as the `run_id` tag.
-`weflayr.runCost(ctx, runId)` returns the cost of the whole job and of each
-step.
+sent to Weflayr as the feature run id, so Weflayr prices the whole job, and it is
+saved with each call. `weflayr.runCost(ctx, runId)` returns the cost of the whole
+job and of each step. A run id is 32 lowercase hex characters, and anything else
+is rejected.
 
 Weflayr also runs an MCP server at `https://mcp.weflayr.com/`, so an agent can
 read cost and margin as a tool.
@@ -228,12 +300,16 @@ read cost and margin as a tool.
 
 ```ts
 await weflayr.setBudget(ctx, "acme", 25); // 25 dollars a month, UTC calendar month
-await weflayr.assertWithinBudget(ctx, "acme"); // throws WeflayrBudgetError once spent
-const status = await weflayr.budget(ctx, "acme"); // { limitUsd, spentUsd, remainingUsd, allowed }
+await weflayr.assertWithinBudget(ctx, "acme"); // throws once spent, or on a listed margin status
+const status = await weflayr.budget(ctx, "acme"); // { limitUsd, spentUsd, remainingUsd, allowed, source, riskStatus }
 ```
 
-A customer without a budget always passes. Spend is the sum of saved cost for
-the month. A call already running when the limit is reached can still finish.
+A customer without a budget always passes. After a sync, spend is Weflayr's real
+cost for the month plus the estimated cost of calls made since shortly before the
+sync (`settleMs`, five minutes by default). In that window a call can be counted
+twice, so spend reads slightly high, never low. Before the first sync, spend is
+the sum of your saved estimates and `source` is `"local"`. A call already running
+when the limit is reached can still finish.
 
 ### Read the numbers
 
@@ -253,16 +329,16 @@ updates live in your UI.
 
 ## How cost is worked out
 
-The gateway does not send a price back with each response, so the component
-uses, in order:
+Weflayr's dashboard is the source of truth for what you were billed, and `sync`
+brings that figure into your database per customer and month. For each saved call
+the gateway does not send a price back, so the component uses, in order:
 
 1. A cost you pass: `costUsd` in the call details, or from `extract` in `track`.
    Saved as `reported`.
 2. An estimate from your `prices` table. Saved as `estimated`.
 3. Zero, saved as `none`, when neither is available.
 
-Weflayr's dashboard is the source of truth for what you were billed. Use the
-saved cost to compare customers and enforce budgets, and fill `prices` from your
+Per-call costs feed your lists and the gap between syncs. Fill `prices` from your
 provider's price list.
 
 ## What is saved
@@ -272,6 +348,7 @@ provider's price list.
 | `calls`   | model call                 | until you run `weflayr.purge(ctx, before)` |
 | `daily`   | customer, call and UTC day | always                                     |
 | `budgets` | customer                   | until cleared                              |
+| `synced`  | customer and month         | replaced by each sync                      |
 
 Queries read the `daily` rows, so they stay fast as `calls` grows. Days and
 months are UTC.
@@ -280,17 +357,19 @@ months are UTC.
 
 - Saving a call never fails the call. If the write fails, the component logs a
   warning and returns your answer.
-- The `plan`, `runId` and any `tags` you pass are sent to Weflayr as tags on the
-  request.
+- The `plan` and any `tags` you pass are sent to Weflayr as tags on the request,
+  and `runId` as its feature run id.
 - Customer names go to Weflayr as written. Use an id or a name you are happy to
   see in its dashboard.
 
 ## Limitations
 
-- Cost is an estimate from your `prices` table unless you pass the cost of a
-  call.
-- A budget compares saved cost with the limit before a call starts, so a call
-  already running can push a customer past it.
+- Between syncs, cost is an estimate from your `prices` table unless you pass the
+  cost of a call.
+- A budget compares spend with the limit before a call starts, so a call already
+  running can push a customer past it.
+- Margin needs revenue in Weflayr, from Stripe, a CSV or `sendRevenue`. On an
+  internal project Weflayr has no margin, and `sync` saves cost only.
 - A customer who is not on the allow list runs the direct call, and that call is
   not saved.
 - `usageByCustomer` and the other reports read one `daily` row per customer,
@@ -308,8 +387,15 @@ months are UTC.
 **Cost shows $0.** The model is missing from `prices`. Add it, in dollars per
 million tokens.
 
-**A budget never stops anyone.** A budget compares saved cost, so it needs
-`prices`, or a `costUsd` on each call.
+**A budget never stops anyone.** Run `sync` on a schedule, or fill `prices`, so
+there is a cost to compare.
+
+**`No customer for the call`.** The call has no signed-in user and no `customer`
+function returned one. Pass the customer, or set `missingCustomer: "warn"`.
+
+**`unknown_routing_strategy` or `invalid_routing_strategy_version`.** The
+strategy id or version does not exist in the project of your key. List them in
+the Weflayr dashboard.
 
 **The gateway returns 402.** Your Weflayr balance is empty. Add credit in the
 Weflayr dashboard.

package/dist/client/api.d.ts

@@ -0,0 +1,116 @@
+export declare const MANAGEMENT_URL = "https://app.weflayr.com/api";
+/** A customer's margin status in Weflayr. The thresholds behind each one are set in the Weflayr dashboard. */
+export type RiskStatus = "healthy" | "watch" | "at_risk" | "unprofitable" | (string & {});
+export type Aggregate = "day" | "week" | "month" | "quarter" | "year" | "all";
+export type CostsInput = {
+    date_from: string;
+    date_to?: string;
+    aggregate?: Aggregate;
+    group_by?: "customer" | "feature" | "model" | "provider" | "call_name";
+    customers?: string[];
+    features?: string[];
+    call_names?: string[];
+    models?: string[];
+    providers?: string[];
+    customer_tags?: Record<string, string | string[]>;
+    run_tags?: Record<string, string | string[]>;
+    apply_credits?: boolean;
+    limit?: number;
+    cursor?: string;
+};
+export type CostRow = {
+    date_from: string;
+    date_to: string;
+    customer?: string;
+    feature?: string;
+    model?: string;
+    provider?: string;
+    call_name?: string;
+    cost: number;
+    avg_feature_run_cost?: number;
+    max_feature_run_cost?: number;
+};
+export type MarginInput = {
+    date_from: string;
+    date_to?: string;
+    aggregate?: Aggregate;
+    group_by?: "customer";
+    customers?: string[];
+    call_names?: string[];
+    filter_customers_based_on_features?: string[];
+    apply_credits?: boolean;
+    limit?: number;
+    cursor?: string;
+};
+export type MarginRow = {
+    date_from: string;
+    date_to: string;
+    customer?: string;
+    revenue: number;
+    cost: number;
+    margin: number;
+    margin_pct: number | null;
+    risk_status: RiskStatus;
+};
+export type Page<T> = {
+    rows: T[];
+    next_cursor: string | null;
+    has_more: boolean;
+};
+export type RevenueRow = {
+    /** The same customer name your model calls carry. */
+    customer_name: string;
+    amount: number;
+    /** "YYYY-MM". Or set month_start and month_end for a period longer than a month. */
+    month?: string;
+    month_start?: string;
+    month_end?: string;
+    /** An id from your billing system. With `upsert`, sending the same id again overwrites the row instead of adding to it. */
+    revenue_id?: string;
+};
+export type CustomerTags = {
+    customer_name: string;
+    /** A string sets the tag, null deletes it. Keys you leave out are not changed. */
+    tags: Record<string, string | null>;
+};
+export declare class WeflayrApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** The first and last day of a "YYYY-MM" month. */
+export declare function monthRange(month: string): {
+    from: string;
+    to: string;
+};
+/**
+ * A small client for Weflayr's management API: cost, margin, revenue and customer tags.
+ * It needs a key with the Management scope.
+ */
+export declare class WeflayrApi {
+    private readonly options;
+    constructor(options?: {
+        apiKey?: string;
+        baseURL?: string;
+    });
+    private key;
+    private post;
+    getCosts(input: CostsInput): Promise<Page<CostRow>>;
+    getMargin(input: MarginInput): Promise<Page<MarginRow>>;
+    /** Books revenue per customer and month. Sends 1,000 rows per request. */
+    setRevenue(rows: RevenueRow[], options?: {
+        upsert?: boolean;
+    }): Promise<{
+        rowsInserted: number;
+    }>;
+    /** Sets tags such as the plan on customers. Sends 1,000 customers per request. */
+    setCustomerTags(customers: CustomerTags[], options?: {
+        upsert?: boolean;
+    }): Promise<{
+        customersUpdated: number;
+    }>;
+    /** What Weflayr has recorded for one customer in one month, in dollars, at list price. */
+    customerCost(customer: string, month: string): Promise<number>;
+    /** One customer's margin for one month, or null when Weflayr has no row for them. */
+    customerMargin(customer: string, month: string): Promise<MarginRow | null>;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/client/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/client/api.ts"],"names":[],"mappings":"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"}

package/dist/client/api.js

@@ -0,0 +1,130 @@
+export const MANAGEMENT_URL = "https://app.weflayr.com/api";
+export class WeflayrApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "WeflayrApiError";
+    }
+}
+const MAX_ROWS = 1000;
+function chunk(items) {
+    const out = [];
+    for (let i = 0; i < items.length; i += MAX_ROWS)
+        out.push(items.slice(i, i + MAX_ROWS));
+    return out;
+}
+/** The first and last day of a "YYYY-MM" month. */
+export function monthRange(month) {
+    const [year, monthIndex] = month.split("-").map(Number);
+    const last = new Date(Date.UTC(year, monthIndex, 0)).getUTCDate();
+    return { from: `${month}-01`, to: `${month}-${String(last).padStart(2, "0")}` };
+}
+/**
+ * A small client for Weflayr's management API: cost, margin, revenue and customer tags.
+ * It needs a key with the Management scope.
+ */
+export class WeflayrApi {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    key() {
+        const key = this.options.apiKey ??
+            process.env.WEFLAYR_MANAGEMENT_KEY ??
+            process.env.WEFLAYR_API_KEY;
+        if (!key) {
+            throw new Error("Set WEFLAYR_MANAGEMENT_KEY, or WEFLAYR_API_KEY with the Management scope.");
+        }
+        return key;
+    }
+    async post(path, body) {
+        let response;
+        try {
+            response = await fetch(`${this.options.baseURL ?? MANAGEMENT_URL}${path}`, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${this.key()}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(30_000),
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith("Set WEFLAYR_"))
+                throw error;
+            const cause = error instanceof Error && error.cause instanceof Error ? error.cause : error;
+            const code = cause.code;
+            throw new Error(`Could not reach Weflayr's management API (${this.options.baseURL ?? MANAGEMENT_URL}${path}): ${cause instanceof Error ? cause.message : String(cause)}${code ? ` [${code}]` : ""}`);
+        }
+        const text = await response.text();
+        if (!response.ok) {
+            let message = text.slice(0, 300);
+            try {
+                const parsed = JSON.parse(text);
+                message = String(parsed.error ?? JSON.stringify(parsed.detail ?? parsed)).slice(0, 300);
+            }
+            catch {
+                // keep the raw text
+            }
+            throw new WeflayrApiError(response.status, `Weflayr ${path} answered ${response.status}: ${message}`);
+        }
+        return JSON.parse(text);
+    }
+    getCosts(input) {
+        return this.post("/costs/", input);
+    }
+    getMargin(input) {
+        return this.post("/margin/", input);
+    }
+    /** Books revenue per customer and month. Sends 1,000 rows per request. */
+    async setRevenue(rows, options = {}) {
+        let inserted = 0;
+        for (const part of chunk(rows)) {
+            const result = await this.post("/revenue/", {
+                rows: part,
+                upsert: options.upsert ?? true,
+            });
+            inserted += result.rows_inserted ?? part.length;
+        }
+        return { rowsInserted: inserted };
+    }
+    /** Sets tags such as the plan on customers. Sends 1,000 customers per request. */
+    async setCustomerTags(customers, options = {}) {
+        let updated = 0;
+        for (const part of chunk(customers)) {
+            const result = await this.post("/customer-tags/", {
+                customers: part,
+                upsert: options.upsert ?? true,
+            });
+            updated += result.customers_updated ?? part.length;
+        }
+        return { customersUpdated: updated };
+    }
+    /** What Weflayr has recorded for one customer in one month, in dollars, at list price. */
+    async customerCost(customer, month) {
+        const { from, to } = monthRange(month);
+        const page = await this.getCosts({
+            date_from: from,
+            date_to: to,
+            aggregate: "all",
+            group_by: "customer",
+            customers: [customer],
+        });
+        return page.rows.reduce((sum, row) => sum + (row.cost ?? 0), 0);
+    }
+    /** One customer's margin for one month, or null when Weflayr has no row for them. */
+    async customerMargin(customer, month) {
+        const { from, to } = monthRange(month);
+        const page = await this.getMargin({
+            date_from: from,
+            date_to: to,
+            aggregate: "all",
+            group_by: "customer",
+            customers: [customer],
+        });
+        return page.rows[0] ?? null;
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/client/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/client/api.ts"],"names":[],"mappings":"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"}