plures 1.3.1 → 1.7.0

package/dist/index.d.ts

@@ -2,6 +2,8 @@ type Option = {
     id: string;
     label: string;
 };
+/** "verifiers" asks ID verified people first; "team" goes straight to your own people ($0.05 per internal vote live). */
+type Route = "verifiers" | "team";
 type TaskStatus = "pending" | "completed" | "expired" | "canceled";
 type Result = {
     answer: string | null;
@@ -15,17 +17,44 @@ type Result = {
     /** The team member who decided, when decided_by is "team". */
     reviewer?: string;
     note?: string;
+    /** How your team voted, when your team decided. */
+    team?: TeamTally;
 };
-/** Set when verifiers didn't all agree and the decision went to your team. */
+type TeamVote = {
+    reviewer: string;
+    answer: string;
+    note: string | null;
+    confirmed: boolean;
+    lead: boolean;
+};
+type TeamTally = {
+    votes: Record<string, number>;
+    agreement: number;
+    required: number;
+    unanimous: boolean;
+    voters: TeamVote[];
+    decided_by_lead: boolean;
+    agreed: boolean;
+};
+/** How your team decides: how many vote, whether they must all agree, a lead for splits, passkey confirmation. */
+type Consensus = {
+    votes: number;
+    unanimous: boolean;
+    lead: string | null;
+    passkey: boolean;
+};
+/** Set when the decision went to your team: straight there (team_only), or because verifiers didn't all agree or answer in time. */
 type Escalation = {
-    reason: "split" | "tie" | "no_answer";
+    reason: "split" | "tie" | "no_answer" | "team_only";
     escalated_at: string;
     verifiers: Result | null;
     team_deadline?: string;
+    lead_called_at?: string;
 };
 type Task = {
     id: string;
     object: "task";
+    app?: string | null;
     mode: "live" | "test";
     status: TaskStatus;
     question: string;
@@ -42,11 +71,23 @@ type Task = {
     result: Result | null;
     escalation?: Escalation | null;
     metadata: Record<string, unknown>;
-    /** Live tasks only: price per answer and what answers have cost so far, in US cents. */
+    /** Where it went: verified people first, or straight to your team. */
+    route?: Route;
+    category?: string | null;
+    /** The named team that decides, or null for your main team. */
+    team?: string | null;
+    team_consensus?: {
+        votes: number;
+        unanimous: boolean;
+        lead: boolean;
+        passkey: boolean;
+    };
+    /** Live tasks only: price per answer and what answers have cost so far, in US cents. A task sent straight to your team is billed per internal vote, billed_as "internal_votes". */
     cost?: {
         per_answer_cents: number;
         answers_billed: number;
         total_cents: number;
+        billed_as?: "answers" | "internal_votes";
     } | null;
     /** Where this decision sits on the Plures ledger, once recorded. */
     ledger?: {
@@ -83,8 +124,203 @@ type CreateTask = {
     escalate?: boolean;
     /** Agreement below which this task goes to your team, 0 to 1. Default from your dashboard. */
     escalate_below?: number;
+    /** "team" skips verified people and sends it straight to your team. Default "verifiers". */
+    route?: Route;
+    /** A label your routing rules match on, like "refunds". */
+    category?: string;
+    /** The name of one of your teams, like "Finance", instead of your main team. */
+    team?: string;
+    /** How many people on the team vote; the majority decides. Default from the team. */
+    team_votes?: number;
+    /** Everyone who votes must agree, or it goes to the team's lead. */
+    team_unanimous?: boolean;
+    /** Which of your apps this task belongs to, like "support-agent". Defaults to the client's app, then your default app. */
+    app?: string;
+};
+/** Your main team, named teams and rules by category. */
+type RoutingRule = {
+    category: string;
+    route: Route;
+    group: string | null;
+    escalate_below: number | null;
+};
+type Routing = {
+    object: "routing";
+    team: {
+        emails: string[];
+        escalate_below: number;
+    } & Consensus;
+    groups: ({
+        name: string;
+        emails: string[];
+    } & Consensus)[];
+    rules: RoutingRule[];
+    internal_vote_cents: number;
+};
+type RoutingUpdate = {
+    team?: {
+        emails?: string[];
+        escalate_below?: number;
+    } & Partial<Consensus>;
+    groups?: ({
+        name: string;
+        emails: string[];
+    } & Partial<Consensus>)[];
+    rules?: {
+        category: string;
+        route?: Route;
+        group?: string | null;
+        escalate_below?: number | null;
+    }[];
+};
+/** Whole number shares of test task outcomes that add up to 100. */
+type Mix = {
+    unanimous?: number;
+    most?: number;
+    split?: number;
+    tie?: number;
+    expired?: number;
+};
+type TestMix = {
+    object: "test_mix";
+    mix: Mix | null;
+    to_team_percent: number;
 };
 /** Prepaid credit for live tasks, in US cents. */
+type MapNode = {
+    id: string;
+    label: string;
+    kind: "input" | "model" | "tool" | "action" | "data" | "output" | "human";
+    file?: string | null;
+    line?: number | null;
+    risk?: "low" | "medium" | "high" | null;
+    note?: string | null;
+};
+type MapDraft = {
+    question: string;
+    options: string[];
+    show?: string[];
+    hide?: string[];
+    instructions?: string | null;
+    route?: "verifiers" | "team";
+    team?: string | null;
+    verifiers?: number;
+    escalate_below?: number | null;
+    example?: string | null;
+};
+type MapCheckpoint = {
+    id?: string;
+    at: string;
+    why: string;
+    category?: string;
+    when?: string | null;
+    status?: "suggested" | "added" | "dismissed";
+    draft?: MapDraft | null;
+    stats?: {
+        tasks: number;
+        done: number;
+        agreement: number | null;
+        to_team: number;
+        internal: number;
+        med_ms: number | null;
+    };
+};
+/** An agent map: the steps of one app's agent and where people check. Written by your coding agent; no source code. */
+type AgentMap = {
+    name?: string | null;
+    summary?: string | null;
+    source?: {
+        repo?: string | null;
+        commit?: string | null;
+        tool?: string | null;
+    };
+    nodes: MapNode[];
+    edges: {
+        from: string;
+        to: string;
+        label?: string | null;
+    }[];
+    checkpoints: MapCheckpoint[];
+};
+type StoredAgentMap = AgentMap & {
+    object: "agent_map";
+    app: string;
+    version: number;
+    created_at?: string;
+    via?: string;
+    url?: string;
+};
+type Rubric = {
+    object: "rubric";
+    name: string;
+    app: string;
+    question: string;
+    options: string[];
+    instructions: string | null;
+    sample_rate: number;
+    verifiers: number;
+    drift_points: number;
+    webhook_url: string | null;
+    seen: number;
+    sampled: number;
+    created_at: string;
+    quality?: {
+        score: number | null;
+        this_week: number | null;
+        baseline: number | null;
+        drift: boolean;
+        graded_this_week: number;
+        grades_this_week: Record<string, number>;
+        days: {
+            day: string;
+            score: number | null;
+            n: number;
+        }[];
+    };
+};
+type RubricParams = {
+    name?: string;
+    question?: string;
+    options?: string[];
+    instructions?: string | null;
+    sample_rate?: number;
+    verifiers?: 1 | 3 | 5;
+    drift_points?: number;
+    webhook_url?: string | null;
+    app?: string;
+};
+type Sample = {
+    object: "sample";
+    rubric: string;
+    sampled: boolean;
+    sample_rate: number;
+    redacted: Record<string, number>;
+    task: Task | null;
+};
+type Release = {
+    object: "release";
+    release: string;
+    app: string;
+    compared: number;
+    b_wins: number;
+    a_wins: number;
+    ties: number;
+    win_rate: number | null;
+    low: number | null;
+    high: number | null;
+    verdict: string;
+};
+/** One agent or product on your account. Tasks, the ledger view and the map are kept per app. */
+type App = {
+    object: "app";
+    id: string;
+    name: string;
+    default: boolean;
+    created_at: string;
+    tasks_30d?: number;
+    waiting?: number;
+    last_task_at?: string | null;
+};
 type Balance = {
     object: "balance";
     currency: "usd";
@@ -105,7 +341,7 @@ type WebhookEvent = {
     created_at: string;
     data: Task;
 };
-declare const VERSION = "1.3.1";
+declare const VERSION = "1.7.0";
 declare class PluresError extends Error {
     readonly status: number;
     readonly type: string;
@@ -114,8 +350,13 @@ declare class PluresError extends Error {
 declare class Plures {
     private base;
     private apiKey;
+    /** The app tasks go to when they don't name one. From opts.app or PLURES_APP. */
+    readonly app: string | null;
+    private ua;
     constructor(apiKey?: string, opts?: {
         baseUrl?: string;
+        app?: string;
+        userAgent?: string;
     });
     private req;
     tasks: {
@@ -128,6 +369,7 @@ declare class Plures {
             status?: TaskStatus;
             limit?: number;
             starting_after?: string;
+            app?: string;
         }) => Promise<{
             object: "list";
             data: Task[];
@@ -140,6 +382,137 @@ declare class Plures {
             intervalMs?: number;
         }) => Promise<Task>;
     };
+    /**
+     * Test keys only. How test tasks behave when they don't set metadata.test_outcome,
+     * so an agent running unchanged sends a share of decisions to your team.
+     * A single task can override it with metadata.test_mix.
+     */
+    testMix: {
+        get: () => Promise<TestMix>;
+        /** For example { unanimous: 70, split: 20, tie: 5, expired: 5 }. Pass null to turn it off. */
+        set: (mix: Mix | null) => Promise<TestMix>;
+        clear: () => Promise<TestMix>;
+    };
+    /**
+     * Where tasks go. set() replaces what you send (team, groups or rules) and keeps the rest.
+     * For example { groups: [{ name: "Finance", emails: ["ap@acme.com"] }], rules: [{ category: "refunds", route: "team", group: "Finance" }] }.
+     */
+    routing: {
+        get: () => Promise<Routing>;
+        set: (update: RoutingUpdate) => Promise<Routing>;
+    };
+    /** Your apps. Each agent you run can be its own app, with its own tasks, ledger view and map. */
+    apps: {
+        list: () => Promise<{
+            object: "list";
+            data: App[];
+            has_more: boolean;
+        }>;
+        /** { name: "Support agent" }, with an optional id like "support-agent". */
+        create: (params: {
+            name: string;
+            id?: string;
+        }) => Promise<App>;
+        retrieve: (id: string) => Promise<App>;
+        /** Rename it, change its id (its tasks move with it), or make it the default. */
+        update: (id: string, params: {
+            name?: string;
+            id?: string;
+            default?: true;
+        }) => Promise<App>;
+        /** Only an app with no tasks can be deleted. */
+        del: (id: string) => Promise<{
+            object: "app";
+            id: string;
+            deleted: true;
+        }>;
+    };
+    /**
+     * Agent maps: where each app's agent needs a person. Your coding agent reads your code and
+     * writes the map; Plures gets only the map. guide() returns the steps it follows.
+     */
+    maps: {
+        guide: () => Promise<string>;
+        retrieve: (app: string) => Promise<StoredAgentMap>;
+        /** Uploads a new version. Checks you already added or dismissed keep that. */
+        upload: (app: string, map: AgentMap) => Promise<StoredAgentMap>;
+        setCheckpoint: (app: string, id: string, status: "added" | "dismissed" | "suggested") => Promise<StoredAgentMap>;
+    };
+    /**
+     * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
+     * early, and compare two versions blind before you ship. Personal details are taken out first.
+     */
+    quality: {
+        /** Send every output; the rubric's sample rate decides which ones people grade. */
+        sample: (p: {
+            rubric: string;
+            output: string;
+            input?: string;
+            app?: string;
+            metadata?: Record<string, unknown>;
+            force?: boolean;
+        }) => Promise<Sample>;
+        /** A blind release check: a is the current version's output, b the new one's, for the same input. */
+        compare: (p: {
+            release: string;
+            a: string;
+            b: string;
+            input?: string;
+            question?: string;
+            instructions?: string;
+            verifiers?: 1 | 3 | 5;
+            app?: string;
+            metadata?: Record<string, unknown>;
+        }) => Promise<{
+            object: "comparison";
+            release: string;
+            task: Task;
+        }>;
+        /** How often people preferred the new version, with a 95% range and a verdict. */
+        release: (name: string, opts?: {
+            app?: string;
+        }) => Promise<Release>;
+        rubrics: {
+            list: (opts?: {
+                app?: string;
+            }) => Promise<{
+                object: "list";
+                data: Rubric[];
+                has_more: boolean;
+            }>;
+            /** { name: "reply_quality", question: "Is this reply correct and kind?", options: ["Good", "Okay", "Bad"], sample_rate: 0.05 } */
+            create: (p: RubricParams & {
+                name: string;
+                question: string;
+                options: string[];
+            }) => Promise<Rubric>;
+            retrieve: (name: string, opts?: {
+                app?: string;
+            }) => Promise<Rubric>;
+            update: (name: string, p: RubricParams) => Promise<Rubric>;
+            del: (name: string, opts?: {
+                app?: string;
+            }) => Promise<{
+                deleted: true;
+            }>;
+        };
+        /** Graded samples as JSON lines (input, output, grade, score, agreement), for fine tuning or an eval set. */
+        export: (rubric: string, opts?: {
+            app?: string;
+            since?: string;
+        }) => Promise<{
+            task_id: string;
+            rubric: string;
+            input: string | null;
+            output: string;
+            grade: string | null;
+            score: number | null;
+            agreement: number | null;
+            graders: number;
+            graded_at: string;
+            metadata: Record<string, unknown>;
+        }[]>;
+    };
     /** Your prepaid credit. A live task that could cost more than available_cents is refused with a 402 insufficient_credits error. */
     balance: () => Promise<Balance>;
     /** Creates a task and waits for people to answer it. */
@@ -155,4 +528,4 @@ declare class Plures {
     static verifyWebhook(rawBody: string, signatureHeader: string | null, secret: string, toleranceSec?: number): Promise<WebhookEvent>;
 }
 
-export { type Balance, type CreateTask, type Escalation, type Option, Plures, PluresError, type Result, type Task, type TaskStatus, VERSION, type WebhookEvent, Plures as default };
+export { type AgentMap, type App, type Balance, type Consensus, type CreateTask, type Escalation, type MapCheckpoint, type MapDraft, type MapNode, type Mix, type Option, Plures, PluresError, type Release, type Result, type Route, type Routing, type RoutingRule, type RoutingUpdate, type Rubric, type RubricParams, type Sample, type StoredAgentMap, type Task, type TaskStatus, type TeamTally, type TeamVote, type TestMix, VERSION, type WebhookEvent, Plures as default };

package/dist/index.js

@@ -1,91 +1,9 @@
-// src/index.ts
-var VERSION = "1.3.1";
-var PluresError = class extends Error {
-  constructor(message, status, type) {
-    super(message);
-    this.status = status;
-    this.type = type;
-  }
-  status;
-  type;
-};
-var Plures = class {
-  base;
-  apiKey;
-  constructor(apiKey, opts = {}) {
-    const key = apiKey ?? (typeof process !== "undefined" ? process.env?.PLURES_API_KEY : void 0);
-    if (!key) throw new Error("Pass your Plures API key, or set PLURES_API_KEY. Get a free test key at https://plures.si/?for=developers#join");
-    this.apiKey = key;
-    this.base = (opts.baseUrl ?? (typeof process !== "undefined" ? process.env?.PLURES_BASE_URL : void 0) ?? "https://plures.si").replace(/\/$/, "");
-  }
-  async req(method, path, body, headers = {}) {
-    for (let attempt = 0; ; attempt++) {
-      const r = await fetch(this.base + path, {
-        method,
-        headers: { authorization: `Bearer ${this.apiKey}`, "user-agent": `plures-js/${VERSION}`, ...body ? { "content-type": "application/json" } : {}, ...headers },
-        body: body ? JSON.stringify(body) : void 0
-      });
-      if (r.status >= 500 && attempt < 2) {
-        await sleep(500 * 2 ** attempt);
-        continue;
-      }
-      const data = await r.json().catch(() => ({}));
-      if (!r.ok) throw new PluresError(data?.error?.message ?? `HTTP ${r.status}`, r.status, data?.error?.type ?? "api_error");
-      return data;
-    }
-  }
-  tasks = {
-    /** Sends a question to verified people. Pass an idempotency key to make retries safe. */
-    create: (params, opts = {}) => this.req("POST", "/api/v1/tasks", params, opts.idempotencyKey ? { "idempotency-key": opts.idempotencyKey } : {}),
-    retrieve: (id) => this.req("GET", `/api/v1/tasks/${encodeURIComponent(id)}`),
-    list: (params = {}) => {
-      const q = new URLSearchParams(Object.entries(params).filter(([, v]) => v != null).map(([k, v]) => [k, String(v)]));
-      return this.req("GET", `/api/v1/tasks${q.size ? `?${q}` : ""}`);
-    },
-    cancel: (id) => this.req("POST", `/api/v1/tasks/${encodeURIComponent(id)}/cancel`),
-    /** Polls until the task is settled. Prefer webhooks in production. */
-    waitFor: async (id, opts = {}) => {
-      const end = Date.now() + (opts.timeoutMs ?? 10 * 6e4);
-      for (; ; ) {
-        const t = await this.tasks.retrieve(id);
-        if (t.status !== "pending") return t;
-        if (Date.now() > end) return t;
-        await sleep(opts.intervalMs ?? 3e3);
-      }
-    }
-  };
-  /** Your prepaid credit. A live task that could cost more than available_cents is refused with a 402 insufficient_credits error. */
-  balance = () => this.req("GET", "/api/v1/balance");
-  /** Creates a task and waits for people to answer it. */
-  async verify(params, opts = {}) {
-    const t = await this.tasks.create(params, { idempotencyKey: opts.idempotencyKey });
-    return t.status === "pending" ? this.tasks.waitFor(t.id, { timeoutMs: opts.timeoutMs }) : t;
-  }
-  /**
-   * Checks the Plures-Signature header on a webhook and returns the parsed event.
-   * Pass the raw request body exactly as received. Throws if the signature is wrong
-   * or older than toleranceSec.
-   */
-  static async verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) {
-    const parts = Object.fromEntries((signatureHeader ?? "").split(",").map((p) => p.split("=", 2)));
-    const t = Number(parts.t);
-    if (!t || !parts.v1) throw new Error("Missing Plures-Signature header");
-    if (Math.abs(Date.now() / 1e3 - t) > toleranceSec) throw new Error("Webhook timestamp is too old");
-    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
-    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${t}.${rawBody}`)));
-    const expected = Array.from(mac, (b) => b.toString(16).padStart(2, "0")).join("");
-    if (!timingSafeEqual(expected, parts.v1)) throw new Error("Webhook signature does not match");
-    return JSON.parse(rawBody);
-  }
-};
-function timingSafeEqual(a, b) {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  return diff === 0;
-}
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-var index_default = Plures;
+import {
+  Plures,
+  PluresError,
+  VERSION,
+  index_default
+} from "./chunk-XOB4CPDP.js";
 export {
   Plures,
   PluresError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plures",
-  "version": "1.3.1",
+  "version": "1.7.0",
   "description": "Human judgment as an API for AI agents. Send a decision to ID verified people and get their consensus back.",
   "keywords": [
     "human-in-the-loop",
@@ -47,12 +47,15 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "build": "tsup src/index.ts src/cli.ts --format esm,cjs --dts --clean",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
     "@types/node": "^22.10.0"
+  },
+  "bin": {
+    "plures": "dist/cli.js"
   }
 }