@listeningkit/treg 0.1.0

package/dist/_generated/server.js

@@ -0,0 +1,80 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+import { actionGeneric, httpActionGeneric, queryGeneric, mutationGeneric, internalActionGeneric, internalMutationGeneric, internalQueryGeneric, } from "convex/server";
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query = queryGeneric;
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery = internalQueryGeneric;
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation = mutationGeneric;
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation = internalMutationGeneric;
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action = actionGeneric;
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction = internalActionGeneric;
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction = httpActionGeneric;
+export const env = globalThis
+    .process.env;
+//# sourceMappingURL=server.js.map

package/dist/_generated/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../_generated/server.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG;AAaH,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAgBvB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAsC,YAAY,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,oBAAoB,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAyC,eAAe,CAAC;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAC3B,uBAAuB,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,MAAM,GAAuC,aAAa,CAAC;AAExE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GACzB,qBAAqB,CAAC;AAExB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,UAAU,GAAsB,iBAAiB,CAAC;AAC/D,MAAM,CAAC,MAAM,GAAG,GAAS,UAAmD;KACzE,OAAO,CAAC,GAAG,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,112 @@
+import type { GenericActionCtx, GenericQueryCtx, FunctionReference } from "convex/server";
+import { buildCallUrl, callFailureReason, TREG_DEFAULT_BASE_URL, type CatalogCall } from "./lib/treg.js";
+/**
+ * Interface representing the internal API exposed by the Treg Convex component.
+ */
+export type TregComponentApi = {
+    treg: {
+        call: FunctionReference<"action", "internal", {
+            owner: string;
+            endpoint: string;
+            params?: Record<string, string | number | boolean>;
+            maxCostUsd?: number;
+        }, any>;
+        getCalls: FunctionReference<"query", "internal", {
+            ownerHash: string;
+            limit?: number;
+        }, Array<{
+            _id: string;
+            _creationTime: number;
+            callId: string;
+            ownerHash: string;
+            endpoint: string;
+            costMicro: number;
+            servedVia?: string;
+            at: number;
+        }>>;
+    };
+};
+export interface TregCallArgs {
+    /**
+     * The owner identifier from your host application (e.g. user id, team id).
+     * Automatically hashed into a privacy-preserving attribution tag before leaving your backend.
+     */
+    owner: string;
+    /**
+     * Catalog endpoint identifier on treg.to (e.g. "spyfu.google.domain.competitors").
+     */
+    endpoint: string;
+    /**
+     * Flat key-value parameters passed to the catalog endpoint query string.
+     */
+    params?: Record<string, string | number | boolean>;
+    /**
+     * Optional spend ceiling for this call in USD (defaults to $0.05).
+     * Treg refuses the call upfront (HTTP 402, charged nothing) if estimated cost exceeds this limit.
+     */
+    maxCostUsd?: number;
+}
+export interface TregCallRecord {
+    _id: string;
+    _creationTime: number;
+    callId: string;
+    ownerHash: string;
+    endpoint: string;
+    costMicro: number;
+    servedVia?: string;
+    at: number;
+}
+/**
+ * Computes a 16-character SHA-256 hex hash for customer attribution tags.
+ */
+export declare function hashOwner(owner: string): Promise<string>;
+/**
+ * Client wrapper for the Treg Convex component.
+ *
+ * Provides a type-safe, ergonomic API for invoking tools in the treg.to catalog
+ * and reading spent call receipts.
+ *
+ * @example
+ * ```ts
+ * import { Treg } from "@superdesign/convex-treg";
+ * import { components } from "./_generated/api";
+ *
+ * export const treg = new Treg(components.treg);
+ *
+ * // Inside a Convex action:
+ * export const findCompetitors = action({
+ *   args: { domain: v.string() },
+ *   handler: async (ctx, args) => {
+ *     const user = await auth.getUser(ctx);
+ *     return await treg.call(ctx, {
+ *       owner: user._id,
+ *       endpoint: "spyfu.google.domain.competitors",
+ *       params: { domain: args.domain, pageSize: 5 },
+ *       maxCostUsd: 0.05,
+ *     });
+ *   },
+ * });
+ * ```
+ */
+export declare class Treg {
+    readonly component: TregComponentApi | any;
+    constructor(component: TregComponentApi | any);
+    /**
+     * Proxies a tool call to https://treg.to with automatic spend guardrails,
+     * fresh idempotency key, and hashed customer attribution.
+     */
+    call<T = unknown>(ctx: {
+        runAction: GenericActionCtx<any>["runAction"];
+    }, args: TregCallArgs): Promise<T>;
+    /**
+     * Retrieves logged spend receipts for a specific owner from the component's internal database.
+     */
+    getCalls(ctx: {
+        runQuery: GenericQueryCtx<any>["runQuery"];
+    }, args: {
+        owner: string;
+        limit?: number;
+    }): Promise<TregCallRecord[]>;
+}
+export { buildCallUrl, callFailureReason, TREG_DEFAULT_BASE_URL, type CatalogCall };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAEzG;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE;QACJ,IAAI,EAAE,iBAAiB,CACrB,QAAQ,EACR,UAAU,EACV;YACE,KAAK,EAAE,MAAM,CAAC;YACd,QAAQ,EAAE,MAAM,CAAC;YACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;YACnD,UAAU,CAAC,EAAE,MAAM,CAAC;SACrB,EACD,GAAG,CACJ,CAAC;QACF,QAAQ,EAAE,iBAAiB,CACzB,OAAO,EACP,UAAU,EACV;YACE,SAAS,EAAE,MAAM,CAAC;YAClB,KAAK,CAAC,EAAE,MAAM,CAAC;SAChB,EACD,KAAK,CAAC;YACJ,GAAG,EAAE,MAAM,CAAC;YACZ,aAAa,EAAE,MAAM,CAAC;YACtB,MAAM,EAAE,MAAM,CAAC;YACf,SAAS,EAAE,MAAM,CAAC;YAClB,QAAQ,EAAE,MAAM,CAAC;YACjB,SAAS,EAAE,MAAM,CAAC;YAClB,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,EAAE,EAAE,MAAM,CAAC;SACZ,CAAC,CACH,CAAC;KACH,CAAC;CACH,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACnD;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,IAAI;aACa,SAAS,EAAE,gBAAgB,GAAG,GAAG;gBAAjC,SAAS,EAAE,gBAAgB,GAAG,GAAG;IAE7D;;;OAGG;IACG,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,GAAG,EAAE;QAAE,SAAS,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,CAAA;KAAE,EACtD,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,CAAC,CAAC;IAIb;;OAEG;IACG,QAAQ,CACZ,GAAG,EAAE;QAAE,QAAQ,EAAE,eAAe,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAA;KAAE,EACnD,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACtC,OAAO,CAAC,cAAc,EAAE,CAAC;CAO7B;AAED,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,KAAK,WAAW,EAAE,CAAC"}

package/dist/client.js

@@ -0,0 +1,64 @@
+import { buildCallUrl, callFailureReason, TREG_DEFAULT_BASE_URL } from "./lib/treg.js";
+/**
+ * Computes a 16-character SHA-256 hex hash for customer attribution tags.
+ */
+export async function hashOwner(owner) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(owner));
+    return [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("")
+        .slice(0, 16);
+}
+/**
+ * Client wrapper for the Treg Convex component.
+ *
+ * Provides a type-safe, ergonomic API for invoking tools in the treg.to catalog
+ * and reading spent call receipts.
+ *
+ * @example
+ * ```ts
+ * import { Treg } from "@superdesign/convex-treg";
+ * import { components } from "./_generated/api";
+ *
+ * export const treg = new Treg(components.treg);
+ *
+ * // Inside a Convex action:
+ * export const findCompetitors = action({
+ *   args: { domain: v.string() },
+ *   handler: async (ctx, args) => {
+ *     const user = await auth.getUser(ctx);
+ *     return await treg.call(ctx, {
+ *       owner: user._id,
+ *       endpoint: "spyfu.google.domain.competitors",
+ *       params: { domain: args.domain, pageSize: 5 },
+ *       maxCostUsd: 0.05,
+ *     });
+ *   },
+ * });
+ * ```
+ */
+export class Treg {
+    component;
+    constructor(component) {
+        this.component = component;
+    }
+    /**
+     * Proxies a tool call to https://treg.to with automatic spend guardrails,
+     * fresh idempotency key, and hashed customer attribution.
+     */
+    async call(ctx, args) {
+        return (await ctx.runAction(this.component.treg.call, args));
+    }
+    /**
+     * Retrieves logged spend receipts for a specific owner from the component's internal database.
+     */
+    async getCalls(ctx, args) {
+        const ownerHash = await hashOwner(args.owner);
+        return (await ctx.runQuery(this.component.treg.getCalls, {
+            ownerHash,
+            limit: args.limit,
+        }));
+    }
+}
+export { buildCallUrl, callFailureReason, TREG_DEFAULT_BASE_URL };
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAoB,MAAM,eAAe,CAAC;AAuEzG;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAAa;IAC3C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACtF,OAAO,CAAC,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;SAC/B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SACjD,IAAI,CAAC,EAAE,CAAC;SACR,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,IAAI;IACa;IAA5B,YAA4B,SAAiC;QAAjC,cAAS,GAAT,SAAS,CAAwB;IAAG,CAAC;IAEjE;;;OAGG;IACH,KAAK,CAAC,IAAI,CACR,GAAsD,EACtD,IAAkB;QAElB,OAAO,CAAC,MAAM,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAM,CAAC;IACpE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,QAAQ,CACZ,GAAmD,EACnD,IAAuC;QAEvC,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9C,OAAO,CAAC,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE;YACvD,SAAS;YACT,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC,CAAqB,CAAC;IAC1B,CAAC;CACF;AAED,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAoB,CAAC"}

package/dist/convex.config.d.ts

@@ -0,0 +1,6 @@
+declare const _default: import("convex/server").ComponentDefinition<any, {
+    readonly TREG_TOKEN: import("convex/values").VString<string | undefined, "optional">;
+    readonly TREG_BASE_URL: import("convex/values").VString<string | undefined, "optional">;
+}>;
+export default _default;
+//# sourceMappingURL=convex.config.d.ts.map

package/dist/convex.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convex.config.d.ts","sourceRoot":"","sources":["../convex.config.ts"],"names":[],"mappings":";;;;AAGA,wBAOG"}

package/dist/convex.config.js

@@ -0,0 +1,11 @@
+import { defineComponent } from "convex/server";
+import { v } from "convex/values";
+export default defineComponent("treg", {
+    env: {
+        // Optional so install never blocks codegen: the action throws
+        // "not switched on yet" when no token is bound, same as FIRECRAWL_API_KEY.
+        TREG_TOKEN: v.optional(v.string()),
+        TREG_BASE_URL: v.optional(v.string()),
+    },
+});
+//# sourceMappingURL=convex.config.js.map

package/dist/convex.config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convex.config.js","sourceRoot":"","sources":["../convex.config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAElC,eAAe,eAAe,CAAC,MAAM,EAAE;IACrC,GAAG,EAAE;QACH,8DAA8D;QAC9D,2EAA2E;QAC3E,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAClC,aAAa,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;KACtC;CACF,CAAC,CAAC"}

package/dist/lib/treg.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure helpers for calling treg.to. No network here — the action owns fetch
+ * so tests can inject a fake. Protocol: GET https://treg.to/call/<id>?params
+ * with an X-Treg-Token header; the upstream answer relays verbatim.
+ */
+export declare const TREG_DEFAULT_BASE_URL = "https://treg.to";
+/** A catalog call: endpoint id plus flat string/number/boolean params. */
+export type CatalogCall = {
+    endpoint: string;
+    params?: Record<string, string | number | boolean>;
+};
+export declare function buildCallUrl(baseUrl: string, call: CatalogCall): string;
+/**
+ * Plain-words reason for a failed catalog call. Never includes a response
+ * body or a key: 402 means the team balance is out (top up, then retry),
+ * 503 means treg's own provider account is out (retry in a minute or pick
+ * the next provider row), anything else stays generic.
+ */
+export declare function callFailureReason(status: number): string;
+//# sourceMappingURL=treg.d.ts.map

package/dist/lib/treg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"treg.d.ts","sourceRoot":"","sources":["../../lib/treg.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD,0EAA0E;AAC1E,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACpD,CAAC;AAEF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAKvE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMxD"}

package/dist/lib/treg.js

@@ -0,0 +1,30 @@
+/**
+ * Pure helpers for calling treg.to. No network here — the action owns fetch
+ * so tests can inject a fake. Protocol: GET https://treg.to/call/<id>?params
+ * with an X-Treg-Token header; the upstream answer relays verbatim.
+ */
+export const TREG_DEFAULT_BASE_URL = "https://treg.to";
+export function buildCallUrl(baseUrl, call) {
+    const query = Object.entries(call.params ?? {})
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+        .join("&");
+    return `${baseUrl.replace(/\/$/, "")}/call/${call.endpoint}${query ? `?${query}` : ""}`;
+}
+/**
+ * Plain-words reason for a failed catalog call. Never includes a response
+ * body or a key: 402 means the team balance is out (top up, then retry),
+ * 503 means treg's own provider account is out (retry in a minute or pick
+ * the next provider row), anything else stays generic.
+ */
+export function callFailureReason(status) {
+    if (status === 401 || status === 403)
+        return "Treg refused the team token";
+    if (status === 402)
+        return "The team balance is out — top up, then try again";
+    if (status === 429)
+        return "Treg is busy, try again in a minute";
+    if (status === 503)
+        return "That provider is out right now, try again in a minute";
+    return `Treg answered HTTP ${status}`;
+}
+//# sourceMappingURL=treg.js.map

package/dist/lib/treg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"treg.js","sourceRoot":"","sources":["../../lib/treg.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,iBAAiB,CAAC;AAQvD,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,IAAiB;IAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;SAC5C,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,kBAAkB,CAAC,GAAG,CAAC,IAAI,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;SACxF,IAAI,CAAC,GAAG,CAAC,CAAC;IACb,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AAC1F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,6BAA6B,CAAC;IAC3E,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,kDAAkD,CAAC;IAC9E,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,qCAAqC,CAAC;IACjE,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,uDAAuD,CAAC;IACnF,OAAO,sBAAsB,MAAM,EAAE,CAAC;AACxC,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,22 @@
+declare const _default: import("convex/server").SchemaDefinition<{
+    calls: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        servedVia?: string | undefined;
+        at: number;
+        callId: string;
+        ownerHash: string;
+        endpoint: string;
+        costMicro: number;
+    }, {
+        callId: import("convex/values").VString<string, "required">;
+        ownerHash: import("convex/values").VString<string, "required">;
+        endpoint: import("convex/values").VString<string, "required">;
+        costMicro: import("convex/values").VFloat64<number, "required">;
+        servedVia: import("convex/values").VString<string | undefined, "optional">;
+        at: import("convex/values").VFloat64<number, "required">;
+    }, "required", "at" | "callId" | "ownerHash" | "endpoint" | "costMicro" | "servedVia">, {
+        by_owner: ["ownerHash", "_creationTime"];
+        by_call: ["callId", "_creationTime"];
+    }, {}, {}>;
+}, true>;
+export default _default;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../schema.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AAGA,wBAcG"}

package/dist/schema.js

@@ -0,0 +1,18 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+export default defineSchema({
+    // Spend receipts, one row per catalog call. Cost comes only from the
+    // X-Treg-Cost-Micro / X-Treg-Call-Id response headers, never from a
+    // provider body. Owner is a SHA-256 hash, never the raw identifier.
+    calls: defineTable({
+        callId: v.string(),
+        ownerHash: v.string(),
+        endpoint: v.string(),
+        costMicro: v.number(),
+        servedVia: v.optional(v.string()),
+        at: v.number(),
+    })
+        .index("by_owner", ["ownerHash"])
+        .index("by_call", ["callId"]),
+});
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAElC,eAAe,YAAY,CAAC;IAC1B,qEAAqE;IACrE,oEAAoE;IACpE,oEAAoE;IACpE,KAAK,EAAE,WAAW,CAAC;QACjB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;QAClB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;QACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QACjC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;KACf,CAAC;SACC,KAAK,CAAC,UAAU,EAAE,CAAC,WAAW,CAAC,CAAC;SAChC,KAAK,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC,CAAC;CAChC,CAAC,CAAC"}

package/dist/treg.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Call any catalogued treg endpoint by id. Auth lives in the app: the
+ * caller passes its already-verified owner string (components have no
+ * ctx.auth), which is hashed before it leaves as the ledger tag. The token
+ * and base URL come only from the component's declared env, never from
+ * arguments; every call carries a spend ceiling (X-Treg-Route-Max-Cost
+ * refuses instead of overspending) and a fresh idempotency key so a retry
+ * is never billed twice. The upstream answer relays verbatim.
+ */
+export declare const call: import("convex/server").RegisteredAction<"public", {
+    params?: Record<string, string | number | boolean> | undefined;
+    maxCostUsd?: number | undefined;
+    endpoint: string;
+    owner: string;
+}, Promise<unknown>>;
+/**
+ * Record a spend receipt into the calls table.
+ */
+export declare const recordReceipt: import("convex/server").RegisteredMutation<"internal", {
+    servedVia?: string | undefined;
+    at: number;
+    callId: string;
+    ownerHash: string;
+    endpoint: string;
+    costMicro: number;
+}, Promise<void>>;
+/**
+ * Read spend receipts for a specific owner hash.
+ */
+export declare const getCalls: import("convex/server").RegisteredQuery<"public", {
+    limit?: number | undefined;
+    ownerHash: string;
+}, Promise<{
+    _id: import("convex/values").GenericId<"calls">;
+    _creationTime: number;
+    servedVia?: string | undefined;
+    at: number;
+    callId: string;
+    ownerHash: string;
+    endpoint: string;
+    costMicro: number;
+}[]>>;
+//# sourceMappingURL=treg.d.ts.map

package/dist/treg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"treg.d.ts","sourceRoot":"","sources":["../treg.ts"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI;;;;;oBAgDf,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;iBAYxB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;KAyBnB,CAAC"}

package/dist/treg.js

@@ -0,0 +1,109 @@
+import { ConvexError } from "convex/values";
+import { v } from "convex/values";
+import { action, internalMutation, query, env } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+import { buildCallUrl, callFailureReason, TREG_DEFAULT_BASE_URL } from "./lib/treg.js";
+/**
+ * Call any catalogued treg endpoint by id. Auth lives in the app: the
+ * caller passes its already-verified owner string (components have no
+ * ctx.auth), which is hashed before it leaves as the ledger tag. The token
+ * and base URL come only from the component's declared env, never from
+ * arguments; every call carries a spend ceiling (X-Treg-Route-Max-Cost
+ * refuses instead of overspending) and a fresh idempotency key so a retry
+ * is never billed twice. The upstream answer relays verbatim.
+ */
+export const call = action({
+    args: {
+        owner: v.string(),
+        endpoint: v.string(),
+        params: v.optional(v.record(v.string(), v.union(v.string(), v.number(), v.boolean()))),
+        maxCostUsd: v.optional(v.number()),
+    },
+    returns: v.any(),
+    handler: async (ctx, args) => {
+        const token = env.TREG_TOKEN;
+        if (!token)
+            throw new ConvexError("Treg is not switched on yet.");
+        const baseUrl = env.TREG_BASE_URL ?? TREG_DEFAULT_BASE_URL;
+        const url = buildCallUrl(baseUrl, { endpoint: args.endpoint, params: args.params });
+        const ownerHash = await sha256Hex(args.owner);
+        const res = await fetch(url, {
+            headers: {
+                "X-Treg-Token": token,
+                "X-Treg-Route-Max-Cost": String(args.maxCostUsd ?? 0.05),
+                "Idempotency-Key": crypto.randomUUID(),
+                "X-Treg-Meta": `customer=${ownerHash}`,
+            },
+            signal: AbortSignal.timeout(55_000),
+        });
+        if (!res.ok)
+            throw new ConvexError(callFailureReason(res.status));
+        const json = (await res.json());
+        // Record spend receipt in internal calls table if headers are present
+        const callId = res.headers.get("x-treg-call-id");
+        const costMicroStr = res.headers.get("x-treg-cost-micro");
+        const servedVia = res.headers.get("x-treg-served-via") ?? undefined;
+        if (callId && costMicroStr) {
+            const costMicro = parseInt(costMicroStr, 10);
+            if (!Number.isNaN(costMicro)) {
+                await ctx.runMutation(internal.treg.recordReceipt, {
+                    callId,
+                    ownerHash,
+                    endpoint: args.endpoint,
+                    costMicro,
+                    servedVia,
+                    at: Date.now(),
+                });
+            }
+        }
+        return json;
+    },
+});
+/**
+ * Record a spend receipt into the calls table.
+ */
+export const recordReceipt = internalMutation({
+    args: {
+        callId: v.string(),
+        ownerHash: v.string(),
+        endpoint: v.string(),
+        costMicro: v.number(),
+        servedVia: v.optional(v.string()),
+        at: v.number(),
+    },
+    handler: async (ctx, args) => {
+        await ctx.db.insert("calls", args);
+    },
+});
+/**
+ * Read spend receipts for a specific owner hash.
+ */
+export const getCalls = query({
+    args: {
+        ownerHash: v.string(),
+        limit: v.optional(v.number()),
+    },
+    returns: v.array(v.object({
+        _id: v.id("calls"),
+        _creationTime: v.number(),
+        callId: v.string(),
+        ownerHash: v.string(),
+        endpoint: v.string(),
+        costMicro: v.number(),
+        servedVia: v.optional(v.string()),
+        at: v.number(),
+    })),
+    handler: async (ctx, args) => {
+        const limit = args.limit ?? 50;
+        return await ctx.db
+            .query("calls")
+            .withIndex("by_owner", (q) => q.eq("ownerHash", args.ownerHash))
+            .order("desc")
+            .take(limit);
+    },
+});
+async function sha256Hex(value) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("").slice(0, 16);
+}
+//# sourceMappingURL=treg.js.map

package/dist/treg.js.map

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

package/dist/tsconfig.build.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../convex.config.ts","../schema.ts","../treg.ts","../client.ts","../lib/treg.ts"],"version":"5.6.3"}

package/lib/treg.ts

@@ -0,0 +1,34 @@
+/**
+ * Pure helpers for calling treg.to. No network here — the action owns fetch
+ * so tests can inject a fake. Protocol: GET https://treg.to/call/<id>?params
+ * with an X-Treg-Token header; the upstream answer relays verbatim.
+ */
+
+export const TREG_DEFAULT_BASE_URL = "https://treg.to";
+
+/** A catalog call: endpoint id plus flat string/number/boolean params. */
+export type CatalogCall = {
+  endpoint: string;
+  params?: Record<string, string | number | boolean>;
+};
+
+export function buildCallUrl(baseUrl: string, call: CatalogCall): string {
+  const query = Object.entries(call.params ?? {})
+    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+    .join("&");
+  return `${baseUrl.replace(/\/$/, "")}/call/${call.endpoint}${query ? `?${query}` : ""}`;
+}
+
+/**
+ * Plain-words reason for a failed catalog call. Never includes a response
+ * body or a key: 402 means the team balance is out (top up, then retry),
+ * 503 means treg's own provider account is out (retry in a minute or pick
+ * the next provider row), anything else stays generic.
+ */
+export function callFailureReason(status: number): string {
+  if (status === 401 || status === 403) return "Treg refused the team token";
+  if (status === 402) return "The team balance is out — top up, then try again";
+  if (status === 429) return "Treg is busy, try again in a minute";
+  if (status === 503) return "That provider is out right now, try again in a minute";
+  return `Treg answered HTTP ${status}`;
+}