plures 1.1.0 → 1.3.0

package/README.md

@@ -44,8 +44,9 @@ if (event.type === "task.completed" && event.data.result?.agreement === 1) {
 
 ## API
 
-- `plures.tasks.create(params, { idempotencyKey? })`: send a task. Params: `question`, `options` (2 to 8, strings or `{ id, label }`), `context`, `image_url`, `instructions`, `verifiers` (1, 3, 5, 7 or 9), `max_verifiers`, `presence_check` (default true), `webhook_url`, `metadata`, `expires_in`.
+- `plures.tasks.create(params, { idempotencyKey? })`: send a task. Params: `question`, `options` (2 to 8, strings or `{ id, label }`), `context`, `image_url`, `audio_url` or `video_url` with `media_seconds` (a clip up to 180 seconds that people play through before answering), `sensitive`, `instructions`, `verifiers` (1, 3, 5, 7 or 9), `max_verifiers`, `presence_check` (default true), `webhook_url`, `metadata`, `expires_in`.
 - `plures.tasks.retrieve(id)`, `plures.tasks.list({ status?, limit?, starting_after? })`, `plures.tasks.cancel(id)`
+- `plures.balance()`: your prepaid credit for live tasks, in cents. Live tasks cost $0.20 per answer (more for clips); a task that could cost more than your available credit throws a `PluresError` with `type` `insufficient_credits` (status 402).
 - `plures.tasks.waitFor(id, { timeoutMs?, intervalMs? })`: poll until settled
 - `plures.verify(params, { timeoutMs?, idempotencyKey? })`: create and wait
 - `Plures.verifyWebhook(rawBody, signatureHeader, secret)`: check a webhook and return the event

package/dist/index.cjs

@@ -26,7 +26,7 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
-var VERSION = "1.1.0";
+var VERSION = "1.3.0";
 var PluresError = class extends Error {
   constructor(message, status, type) {
     super(message);
@@ -81,6 +81,8 @@ var Plures = class {
       }
     }
   };
+  /** 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 });

package/dist/index.d.cts

@@ -32,12 +32,27 @@ type Task = {
     context: string | null;
     image_url: string | null;
     instructions: string | null;
+    audio_url?: string | null;
+    video_url?: string | null;
+    media_seconds?: number | null;
+    sensitive?: boolean;
     options: Option[];
     verifiers: number;
     presence_check?: boolean;
     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. */
+    cost?: {
+        per_answer_cents: number;
+        answers_billed: number;
+        total_cents: number;
+    } | null;
+    /** Where this decision sits on the Plures ledger, once recorded. */
+    ledger?: {
+        seq: number;
+        url: string;
+    } | null;
     webhook_url: string | null;
     created_at: string;
     completed_at: string | null;
@@ -48,6 +63,14 @@ type CreateTask = {
     options: (string | Option)[];
     context?: string;
     image_url?: string;
+    /** A recording people play through before answering, up to 3 minutes. Needs media_seconds. */
+    audio_url?: string;
+    /** A video people play through before answering, up to 3 minutes. Needs media_seconds. Not with audio_url. */
+    video_url?: string;
+    /** The clip's length in seconds, 1 to 180. Required with audio_url or video_url; pay scales with it. */
+    media_seconds?: number;
+    /** Disturbing content: only verifiers who opted in get it, behind a warning. Default false. */
+    sensitive?: boolean;
     instructions?: string;
     verifiers?: 1 | 3 | 5 | 7 | 9;
     max_verifiers?: number;
@@ -61,13 +84,28 @@ type CreateTask = {
     /** Agreement below which this task goes to your team, 0 to 1. Default from your dashboard. */
     escalate_below?: number;
 };
+/** Prepaid credit for live tasks, in US cents. */
+type Balance = {
+    object: "balance";
+    currency: "usd";
+    available_cents: number;
+    held_cents: number;
+    balance_cents: number;
+    price_per_unit_cents: number;
+    billing: "prepaid" | "invoice";
+    auto_topup: {
+        enabled: boolean;
+        below_cents: number;
+        amount_cents: number;
+    };
+};
 type WebhookEvent = {
     id: string;
     type: "task.completed" | "task.expired" | "task.canceled";
     created_at: string;
     data: Task;
 };
-declare const VERSION = "1.1.0";
+declare const VERSION = "1.3.0";
 declare class PluresError extends Error {
     readonly status: number;
     readonly type: string;
@@ -102,6 +140,8 @@ declare class Plures {
             intervalMs?: number;
         }) => Promise<Task>;
     };
+    /** 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. */
     verify(params: CreateTask, opts?: {
         timeoutMs?: number;
@@ -115,4 +155,4 @@ declare class Plures {
     static verifyWebhook(rawBody: string, signatureHeader: string | null, secret: string, toleranceSec?: number): Promise<WebhookEvent>;
 }
 
-export { type CreateTask, type Escalation, type Option, Plures, PluresError, type Result, type Task, type TaskStatus, VERSION, type WebhookEvent, Plures as default };
+export { type Balance, type CreateTask, type Escalation, type Option, Plures, PluresError, type Result, type Task, type TaskStatus, VERSION, type WebhookEvent, Plures as default };

package/dist/index.d.ts

@@ -32,12 +32,27 @@ type Task = {
     context: string | null;
     image_url: string | null;
     instructions: string | null;
+    audio_url?: string | null;
+    video_url?: string | null;
+    media_seconds?: number | null;
+    sensitive?: boolean;
     options: Option[];
     verifiers: number;
     presence_check?: boolean;
     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. */
+    cost?: {
+        per_answer_cents: number;
+        answers_billed: number;
+        total_cents: number;
+    } | null;
+    /** Where this decision sits on the Plures ledger, once recorded. */
+    ledger?: {
+        seq: number;
+        url: string;
+    } | null;
     webhook_url: string | null;
     created_at: string;
     completed_at: string | null;
@@ -48,6 +63,14 @@ type CreateTask = {
     options: (string | Option)[];
     context?: string;
     image_url?: string;
+    /** A recording people play through before answering, up to 3 minutes. Needs media_seconds. */
+    audio_url?: string;
+    /** A video people play through before answering, up to 3 minutes. Needs media_seconds. Not with audio_url. */
+    video_url?: string;
+    /** The clip's length in seconds, 1 to 180. Required with audio_url or video_url; pay scales with it. */
+    media_seconds?: number;
+    /** Disturbing content: only verifiers who opted in get it, behind a warning. Default false. */
+    sensitive?: boolean;
     instructions?: string;
     verifiers?: 1 | 3 | 5 | 7 | 9;
     max_verifiers?: number;
@@ -61,13 +84,28 @@ type CreateTask = {
     /** Agreement below which this task goes to your team, 0 to 1. Default from your dashboard. */
     escalate_below?: number;
 };
+/** Prepaid credit for live tasks, in US cents. */
+type Balance = {
+    object: "balance";
+    currency: "usd";
+    available_cents: number;
+    held_cents: number;
+    balance_cents: number;
+    price_per_unit_cents: number;
+    billing: "prepaid" | "invoice";
+    auto_topup: {
+        enabled: boolean;
+        below_cents: number;
+        amount_cents: number;
+    };
+};
 type WebhookEvent = {
     id: string;
     type: "task.completed" | "task.expired" | "task.canceled";
     created_at: string;
     data: Task;
 };
-declare const VERSION = "1.1.0";
+declare const VERSION = "1.3.0";
 declare class PluresError extends Error {
     readonly status: number;
     readonly type: string;
@@ -102,6 +140,8 @@ declare class Plures {
             intervalMs?: number;
         }) => Promise<Task>;
     };
+    /** 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. */
     verify(params: CreateTask, opts?: {
         timeoutMs?: number;
@@ -115,4 +155,4 @@ declare class Plures {
     static verifyWebhook(rawBody: string, signatureHeader: string | null, secret: string, toleranceSec?: number): Promise<WebhookEvent>;
 }
 
-export { type CreateTask, type Escalation, type Option, Plures, PluresError, type Result, type Task, type TaskStatus, VERSION, type WebhookEvent, Plures as default };
+export { type Balance, type CreateTask, type Escalation, type Option, Plures, PluresError, type Result, type Task, type TaskStatus, VERSION, type WebhookEvent, Plures as default };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-var VERSION = "1.1.0";
+var VERSION = "1.3.0";
 var PluresError = class extends Error {
   constructor(message, status, type) {
     super(message);
@@ -54,6 +54,8 @@ var Plures = class {
       }
     }
   };
+  /** 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 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plures",
-  "version": "1.1.0",
+  "version": "1.3.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",