@specstream/sdk 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @specstream/sdk
 
-TypeScript client for [SpecStream](https://specstream.ai), the live web data engine for teams and agents. Describe the list you need in plain words; SpecStream reads the web where those things live, hands back only the matches, each with the page it came from, and you pay only for the matches.
+TypeScript client for [SpecStream](https://specstream.ai), the live web data engine for teams and agents. Describe the list you need in plain words; SpecStream reads the web where those things live, hands back only the matches, each with the page it came from, and you pay for each result delivered.
 
 The client has no runtime dependencies and needs Node 22 or newer. It uses the same account, permissions, projects and balance as the workspace.
 
@@ -64,7 +64,7 @@ New accounts start with $10 of work for 30 days, no card. A delivered result cos
 ## Links
 
 - [SDK docs](https://specstream.ai/docs/sdk) and [API docs](https://specstream.ai/docs/api)
-- [Source and issues](https://github.com/Specstreamai/specstream-tools)
+- [Source and issues](https://github.com/specstream/specstream-tools)
 - [Python client](https://pypi.org/project/specstream-client/)
 - Support: support@specstream.ai
 

package/dist/index.d.ts

@@ -2,7 +2,10 @@
 import type { Schemas } from "./work-types.js";
 export type { Schemas } from "./work-types.js";
 export declare const FAMILIES: readonly ["local_business", "creator", "organization", "storefront_product", "app_listing", "job_posting", "scholarly_work", "tender", "grant", "software_repository", "software_package", "dataset", "clinical_trial", "regulatory_document", "vulnerability", "book", "podcast", "web_page", "knowledge_entity", "person"];
-export type EntityType = (typeof FAMILIES)[number];
+/** A record kind the service names today. FAMILIES lists them; they are examples, not a limit. */
+export type KnownEntityType = (typeof FAMILIES)[number];
+/** A record kind is an open string: any kind name a reading gives is valid. */
+export type EntityType = KnownEntityType | (string & {});
 export declare const DEFAULT_BASE_URL = "https://api.specstream.ai";
 export declare class SpecstreamError extends Error {
     readonly status: number | null;
@@ -28,7 +31,7 @@ export declare class Client {
     private readonly exportOrigin?;
     private readonly timeoutMs;
     constructor(options: ClientOptions);
-    families(): readonly EntityType[];
+    families(): readonly KnownEntityType[];
     compile(q: string, locale?: string): Promise<JsonMap>;
     editSpec(ast: JsonMap, operations?: JsonMap[]): Promise<JsonMap>;
     specOptions(target: string): Promise<JsonMap>;
@@ -139,11 +142,19 @@ export declare class Client {
     quoteCapacityWork(request: Schemas["CapacityQuoteRequest"]): Promise<Schemas["CapacityQuoteData"]>;
     getCapacityQuote(quoteId: string): Promise<Schemas["CapacityQuoteData"]>;
     authorizeCapacityWork(request: Schemas["CapacityAuthorizeRequest"]): Promise<Schemas["CapacityExecutionData"]>;
+    startCapacityRequest(request: Schemas["CapacityStartRequest"]): Promise<Schemas["CapacityStartData"]>;
     getCapacityRequest(requestKey: string, query?: {
         "project_id"?: string;
     }): Promise<{
         [key: string]: unknown;
     }>;
+    getCapacityRequestRows(requestKey: string, query?: {
+        "project_id"?: string;
+        "cursor"?: string;
+        "limit"?: number;
+    }): Promise<{
+        [key: string]: unknown;
+    }>;
     getCapacityExecution(findId: string): Promise<Schemas["CommerceData"]>;
     createCapacityFunding(request: Schemas["CapacityFundingRequest"]): Promise<Schemas["CapacityFundingData"]>;
     getCapacityFunding(fundingId: string): Promise<Schemas["CapacityFundingData"]>;

package/dist/index.js

@@ -51,8 +51,8 @@ export class SpecstreamError extends Error {
     }
 }
 export function assertFamily(entityType) {
-    if (!FAMILIES.includes(entityType)) {
-        throw new Error(`unsupported entity_type ${entityType}`);
+    if (typeof entityType !== "string" || !entityType.trim()) {
+        throw new Error("entity_type must be a non-empty string");
     }
     return entityType;
 }
@@ -459,6 +459,10 @@ export class Client {
         requireWorkAuthorization(request);
         return this.request("POST", path, request);
     }
+    startCapacityRequest(request) {
+        let path = `/v1/capacity/requests`;
+        return this.request("POST", path, request);
+    }
     getCapacityRequest(requestKey, query = {}) {
         let path = `/v1/capacity/requests/${encodeURIComponent(requestKey)}`;
         const queryString = new URLSearchParams();
@@ -469,6 +473,16 @@ export class Client {
             path += "?" + queryString.toString();
         return this.request("GET", path);
     }
+    getCapacityRequestRows(requestKey, query = {}) {
+        let path = `/v1/capacity/requests/${encodeURIComponent(requestKey)}/rows`;
+        const queryString = new URLSearchParams();
+        for (const [key, value] of Object.entries(query))
+            if (value !== undefined && value !== null)
+                queryString.set(key, String(value));
+        if (queryString.size)
+            path += "?" + queryString.toString();
+        return this.request("GET", path);
+    }
     getCapacityExecution(findId) {
         let path = `/v1/capacity/executions/${encodeURIComponent(findId)}`;
         return this.request("GET", path);
@@ -966,7 +980,7 @@ export class Client {
             Authorization: token,
             Accept: "application/json",
             "Content-Type": "application/json",
-            "User-Agent": "specstream-typescript/1.1.0",
+            "User-Agent": "specstream-typescript/1.2.0",
         };
     }
     async request(method, path, body) {

package/dist/work-types.d.ts

@@ -174,8 +174,6 @@ export interface Schemas {
         "members_used": number;
         "current_lists_limit": (number | null);
         "current_lists_used": number;
-        "finds_at_once": number;
-        "finds_per_hour": number;
         "capabilities": Schemas["CapacityPlanCapabilities"];
         "unlock": {
             [key: string]: "starter" | "pro" | "team" | "enterprise";
@@ -245,7 +243,8 @@ export interface Schemas {
     "CapacityMembershipData": {
         "plan_id": string;
         "pending_plan_id"?: (string | null);
-        "billed_by"?: "card" | "app_store" | "google_play";
+        "billed_by"?: "card" | "app_store" | "google_play" | "vercel" | "digitalocean";
+        "manage_url"?: (string | null);
         "next_plan"?: (string | null);
         "upgrade_pending"?: boolean;
         "payment_action_url"?: (string | null);
@@ -264,6 +263,15 @@ export interface Schemas {
     "CapacityMembershipStatusData": {
         "membership"?: (Schemas["CapacityMembershipData"] | null);
     };
+    "CapacityPartnerData": {
+        "share_percent": number;
+        "months": number;
+        "clearing_days": number;
+        "pending_cents": number;
+        "payable_cents": number;
+        "paid_cents": number;
+        "paying_accounts": number;
+    };
     "CapacityPlanCapabilities": {
         "schedules": boolean;
         "deliveries": boolean;
@@ -293,6 +301,7 @@ export interface Schemas {
             "check_unit_cents"?: number;
             "required_check_unit_cents"?: number;
             "required_check_allowance"?: number;
+            "unchanged_unit_cents"?: number;
             "related_block_cents"?: number;
             "undelivered_unit_cents"?: number;
             "retail_rate"?: {
@@ -329,6 +338,7 @@ export interface Schemas {
         "signed_up": number;
         "rewarded": number;
         "earned_cents": number;
+        "partner"?: (Schemas["CapacityPartnerData"] | null);
     };
     "CapacityReferralVisitData": {
         "attributed": boolean;
@@ -368,6 +378,31 @@ export interface Schemas {
         "calendar_schedule"?: (Schemas["CalendarSchedule"] | null);
         "valid_until": string;
     };
+    "CapacityStartData": {
+        "idempotency_key": string;
+        "state": "reading" | "started" | "needs_edit" | "above_maximum" | "failed";
+        "message"?: (string | null);
+        "read_back"?: (string | null);
+        "maximum_cents"?: (number | null);
+        "find_id"?: (string | null);
+        "retry_after_seconds"?: (number | null);
+        "queue_position"?: (number | null);
+    };
+    "CapacityStartRequest": {
+        "q"?: (string | null);
+        "rows"?: (Array<{
+            [key: string]: (string | number | boolean | null);
+        }> | null);
+        "fields"?: (Array<string> | null);
+        "requested_units"?: number;
+        "confirm_max_cents": number;
+        "maximum_price_usd"?: (number | null);
+        "idempotency_key": string;
+        "locale"?: string;
+        "callback_url"?: (string | null);
+        "callback_on"?: "start" | "done";
+        "one_row_per"?: (string | null);
+    };
     "CapacityTrialEndingData": {
         "event"?: "trial_ending";
         "expires_at": string;
@@ -451,7 +486,7 @@ export interface Schemas {
         "billed_units"?: Array<Schemas["BilledUnit"]>;
         "shortfall"?: (Schemas["Shortfall"] | null);
     };
-    "CompilerStatus": "runnable" | "needs_edit" | "rejected" | "capability_pending" | "compiler_unavailable" | "unquoted_plan";
+    "CompilerStatus": "runnable" | "needs_edit" | "rejected" | "capability_pending" | "compiler_unavailable" | "unquoted_plan" | "pending";
     "ConditionGrade": {
         "part_id": string;
         "field_id": (string | null);
@@ -588,13 +623,14 @@ export interface Schemas {
         "platforms"?: Array<string>;
         "searches"?: Array<string>;
         "role_phrases"?: Array<string>;
+        "record_words"?: Array<string>;
         "seed_identifiers"?: {
             [key: string]: string;
         };
     };
     "DisplayAbsence": "Not published" | "Couldn't check";
-    "EntityKind": "place" | "creator" | "organization" | "storefront_product" | "app_listing" | "job_posting" | "scholarly_work" | "tender" | "grant" | "software_repository" | "software_package" | "dataset" | "clinical_trial" | "regulatory_document" | "vulnerability" | "book" | "podcast" | "web_page" | "knowledge_entity" | "person";
-    "EntityType": "local_business" | "creator" | "organization" | "storefront_product" | "app_listing" | "job_posting" | "scholarly_work" | "tender" | "grant" | "software_repository" | "software_package" | "dataset" | "clinical_trial" | "regulatory_document" | "vulnerability" | "book" | "podcast" | "web_page" | "knowledge_entity" | "person";
+    "EntityKind": string;
+    "EntityType": string;
     "EquivalenceRecord": {
         "assessment_id": string;
         "provider": string;
@@ -613,7 +649,7 @@ export interface Schemas {
             [key: string]: unknown;
         };
     };
-    "ErrorCode": "unsupported_query" | "unsupported_predicate" | "unsupported_entity_family" | "ambiguous_geo" | "capability_pending" | "source_blocked" | "challenge_page" | "unquoted_plan" | "compiler_unavailable" | "parse_failed" | "payments_not_live" | "capacity" | "kill_switch" | "internal_failure" | "plan_required";
+    "ErrorCode": "unsupported_query" | "unsupported_predicate" | "unsupported_entity_family" | "ambiguous_geo" | "capability_pending" | "source_blocked" | "challenge_page" | "unquoted_plan" | "compiler_unavailable" | "parse_failed" | "payments_not_live" | "capacity" | "kill_switch" | "internal_failure" | "plan_required" | "invalid_token";
     "ErrorEnvelope": {
         "error": Schemas["ErrorBody"];
     };
@@ -674,6 +710,10 @@ export interface Schemas {
         "source_pointer"?: (string | null);
         "source_response_sha256"?: (string | null);
         "source_time"?: (Schemas["EvidenceTime"] | null);
+        "source_raw"?: ({
+            [key: string]: unknown;
+        } | null);
+        "capability_id"?: (string | null);
     };
     "FileImportCommand": {
         "import_id": string;
@@ -748,6 +788,9 @@ export interface Schemas {
         "accepted_count": number;
         "rows": Array<Schemas["AcceptedRow"]>;
         "possible"?: Array<Schemas["PossibleRow"]>;
+        "flat_rows"?: Array<{
+            [key: string]: unknown;
+        }>;
         "entitlement": string;
         "commerce"?: (Schemas["CommerceData"] | null);
         "next_cursor"?: (string | null);
@@ -1023,6 +1066,7 @@ export interface Schemas {
     };
     "MeData": {
         "account_id"?: (string | null);
+        "email"?: (string | null);
         "guest": boolean;
         "spend_ceiling_cents"?: number;
         "amount_spent_cents"?: number;
@@ -1151,6 +1195,8 @@ export interface Schemas {
         "compiler_version": string;
         "ast_hash": (string | null);
         "canonical_sentence": (string | null);
+        "notice"?: (string | null);
+        "read_back"?: (string | null);
     };
     "PasskeyComplete": {
         "challenge_id": string;
@@ -1352,6 +1398,9 @@ export interface Schemas {
         "output_fields"?: Array<Schemas["OutputField"]>;
         "worded_conditions"?: Array<Schemas["WordedCondition"]>;
         "worded_outputs"?: Array<Schemas["WordedOutput"]>;
+        "contact_off"?: Array<"email" | "phone">;
+        "record_fields"?: Array<string>;
+        "each_location"?: boolean;
         "sort": Array<Schemas["SortKey"]>;
         "locale": string;
         "inferred": Array<Schemas["InferredClause"]>;
@@ -1940,6 +1989,7 @@ export interface Schemas {
         "source_find_id"?: (string | null);
         "project_id"?: (string | null);
         "context"?: string;
+        "q"?: (string | null);
     } & ({
         "ast": NonNullable<unknown>;
         "source_find_id"?: null;
@@ -1992,10 +2042,12 @@ export interface Schemas {
         "ast": Schemas["QueryAst"];
         "name"?: (string | null);
         "context"?: (string | null);
+        "q"?: (string | null);
     };
     "SseComplete": {
         "row_count": number;
         "stop_reason": Schemas["StopReason"];
+        "message"?: (string | null);
     };
     "SseError": {
         "code": Schemas["ErrorCode"];
@@ -2054,7 +2106,7 @@ export interface Schemas {
     "SseZero": {
         "cause": string;
     };
-    "StopReason": "complete_target" | "saturated_discovery" | "budget_reserved_exhausted" | "wall_clock" | "fetch_count" | "source_blocked" | "unsupported_predicate" | "zero_after_filters" | "user_cancel" | "capacity";
+    "StopReason": "complete_target" | "saturated_discovery" | "budget_reserved_exhausted" | "wall_clock" | "fetch_count" | "source_blocked" | "unsupported_predicate" | "zero_after_filters" | "user_cancel" | "capacity" | "model_unavailable";
     "StoreCardTransferRequest": {
         "plan_id": string;
         "idempotency_key": string;
@@ -2242,7 +2294,7 @@ export interface Schemas {
         "detail_id": string;
         "words": string;
         "description": string;
-        "value_type"?: "text" | "number" | "date" | "url" | "email" | "phone" | "yes_no";
+        "value_type"?: "text" | "number" | "date" | "url" | "email" | "phone" | "yes_no" | "place";
         "required"?: boolean;
     };
     "WorkspaceAuditEvent": {
@@ -2469,6 +2521,7 @@ export interface Schemas {
         "snippet": string;
         "project_id"?: (string | null);
         "collection_id"?: (string | null);
+        "find_id"?: (string | null);
         "record_id"?: (string | null);
         "note_id"?: (string | null);
         "imported"?: (boolean | null);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@specstream/sdk",
-  "version": "1.1.0",
-  "description": "TypeScript client for SpecStream: finished lists from the live web, every row with its source, priced before anything runs.",
+  "version": "1.2.0",
+  "description": "TypeScript client for building lead lists and company lists from the live web. Every match comes with its source, priced before it runs.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -49,11 +49,11 @@
   "homepage": "https://specstream.ai/docs/sdk",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Specstreamai/specstream-tools.git",
+    "url": "git+https://github.com/specstream/specstream-tools.git",
     "directory": "packages/sdk-ts"
   },
   "bugs": {
-    "url": "https://github.com/Specstreamai/specstream-tools/issues"
+    "url": "https://github.com/specstream/specstream-tools/issues"
   },
   "publishConfig": {
     "access": "public"