@awesomate/platform-sdk 0.1.0

package/dist/esm/types.d.ts

@@ -0,0 +1,517 @@
+/**
+ * Every call resolves to one of three outcomes and never throws on the request path:
+ * a 2xx with typed data; a 4xx with the platform's error envelope; or `unavailable`
+ * (5xx, timeout, network failure, missing config) so callers can answer 503/202 cleanly.
+ */
+export type PlatformResult<T> = {
+    ok: true;
+    status: number;
+    data: T;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+    message?: string;
+    requestId?: string;
+    retryAfter?: string;
+} | {
+    ok: false;
+    reason: "unavailable";
+};
+export type PlatformFailure = Exclude<PlatformResult<never>, {
+    ok: true;
+}>;
+export type KeyClass = "q" | "p" | "i" | "a" | "s" | "u";
+export type AnswerStatus = "ok" | "no_results" | "failed_validation" | "error";
+export type AgentName = "knowledge" | "content" | "social" | "assistant" | (string & {});
+export interface AnswerRequest {
+    /** ≤ 2000 chars. */
+    question: string;
+    /** ≤ 128 chars, end-user session id; omitted → the platform generates one and echoes it. */
+    session?: string;
+    /** Default = the tenant's `default_agent`. */
+    agent?: AgentName;
+    /** 1–10, default 3. */
+    max_sources?: number;
+    /** v2: run a published agent by id with the v1 response shape. */
+    agent_id?: string;
+}
+export interface AnswerSource {
+    ref: number;
+    doc_id: string;
+    title: string;
+    kind: string;
+    section_path: string;
+    locator: string | null;
+    url: string | null;
+    excerpt: string;
+}
+export interface Citation {
+    doc_id: string;
+    section_path: string;
+}
+export interface Answer {
+    tenant: string;
+    status: AnswerStatus;
+    /** Internal form with `[[doc_id#Section]]` markers; empty unless status is `ok`. */
+    answer: string;
+    /** End-user form: markers replaced by [1], [2]…; the tenant's `no_answer_message` when status ≠ ok. */
+    answer_plain: string;
+    sources: AnswerSource[];
+    citations: Citation[];
+    score: number;
+    attempts: number;
+    mode: string;
+    retrieved: Citation[];
+    tools: string[];
+    session: string;
+}
+/** The `meta` SSE event — the validated result minus the text that already streamed. */
+export interface AnswerMeta {
+    status: AnswerStatus;
+    citations: Citation[];
+    score: number;
+    attempts: number;
+    mode: string;
+    retrieved: Array<Citation & Record<string, unknown>>;
+    tools: string[];
+    sources: Array<Record<string, unknown>>;
+    thread?: string;
+    repaired?: "stripped_uncited" | "regenerated" | "truncated" | (string & {});
+    /** v2 grounded_chat agents: the one documented client-side retraction. */
+    reply_override?: string;
+    [extra: string]: unknown;
+}
+export type AnswerStreamEvent = {
+    event: "sources";
+    sources: Array<Record<string, unknown>>;
+} | {
+    event: "answer";
+    text: string;
+} | {
+    event: "reply";
+    text: string;
+} | {
+    event: "meta";
+    meta: AnswerMeta;
+} | {
+    event: "done";
+} | {
+    event: "error";
+    message: string;
+};
+export interface QueryHit {
+    doc_id: string;
+    section_path: string;
+    title: string;
+    kind: string | null;
+    excerpt: string;
+    score: number | null;
+    url: string | null;
+    locator: string | null;
+}
+export interface QueryResponse {
+    tenant: string;
+    query: string;
+    hits: QueryHit[];
+}
+export interface QueryParams {
+    q: string;
+    /** 1–20, default 8. */
+    limit?: number;
+    kind?: string;
+    /** One dataset (`knowledge`, `content`, `social`, …); omitted → fan-out over everything enabled. */
+    dataset?: string;
+}
+export interface Whoami {
+    tenant: string;
+    display_name: string;
+    status: string;
+    plan: string;
+    key: {
+        id: string;
+        class: string;
+        scope?: string;
+        scopes?: string[];
+        expires_at?: string | null;
+    };
+    datasets: string[];
+    counts: {
+        sources: number;
+        chunks: number;
+        indexed: number;
+    };
+    last_indexed_at: string | null;
+}
+export interface Status {
+    tenant?: string;
+    jobs: {
+        queued: number;
+        running: number;
+        failed: number;
+    };
+    time_to_searchable_p50_min: number | null;
+    sources_by_kind: Record<string, number>;
+}
+export interface Feedback {
+    session?: string;
+    /** 1–10, the `sources[].ref` being rated. */
+    ref?: number;
+    rating: "up" | "down";
+    /** ≤ 500 chars. */
+    comment?: string;
+}
+export type IngestKind = "markdown" | "pdf" | "facebook-export" | "html-url" | "html-sitemap" | "video" | "audio" | "image" | "data-import" | (string & {});
+export type JobStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled";
+/** One entry of `IngestJob.stages`, as the worker pipeline writes it. */
+export interface JobStage {
+    status: string;
+    at?: string;
+    error?: string | null;
+    [extra: string]: unknown;
+}
+export interface IngestJob {
+    job_id: string;
+    kind: IngestKind;
+    status: JobStatus;
+    /** Keyed by stage name (`fetch`, `parse`, `upsert`, `enrich`, `index`, `finalize`, …), not an array. */
+    stages?: Record<string, JobStage>;
+    result_summary?: Record<string, unknown> | null;
+    error?: string | null;
+    cost?: Record<string, unknown> | null;
+    created_at: string;
+    started_at?: string | null;
+    finished_at?: string | null;
+}
+export interface UploadTicket {
+    upload_id: string;
+    key: string;
+    put_url?: string;
+    multipart?: {
+        upload_id: string;
+        part_urls: string[];
+    };
+    expires_at: string;
+}
+export interface CreateUploadBody {
+    filename: string;
+    mime: string;
+    size_bytes: number;
+    sha256?: string;
+}
+export interface CompleteUploadBody {
+    sha256?: string;
+    parts?: Array<{
+        etag: string;
+        part: number;
+    }>;
+}
+export type CreateJobBody = {
+    kind: IngestKind;
+    upload_id: string;
+    options?: Record<string, unknown>;
+} | {
+    kind: IngestKind;
+    url: string;
+    options?: Record<string, unknown>;
+};
+export interface Enqueued {
+    job_id: string;
+    status: JobStatus;
+    position?: number;
+}
+export interface JobsPage {
+    jobs: IngestJob[];
+    next_cursor: string | null;
+}
+export interface DatasetSummary {
+    dataset_id: string;
+    name: string;
+    description?: string | null;
+    grain?: string | null;
+    status: string;
+    record_count: number;
+    period_from?: string | null;
+    period_to?: string | null;
+    updated_at: string;
+}
+export interface DataQuery {
+    dataset: string;
+    measures: Array<{
+        column: string;
+        agg: "sum" | "avg" | "min" | "max" | "count" | "last";
+    }>;
+    dimensions?: string[];
+    time?: {
+        grain?: string;
+        preset?: string;
+        from?: string;
+        to?: string;
+    };
+    filters?: Array<{
+        column: string;
+        op: "eq" | "neq" | "in" | "gte" | "lte" | "contains";
+        value: unknown;
+    }>;
+    compare?: "previous_period" | "previous_year" | null;
+    order_by?: Array<{
+        field: string;
+        dir: "asc" | "desc";
+    }>;
+    limit?: number;
+}
+export interface DataQueryResult {
+    dataset_id: string;
+    columns: Array<Record<string, unknown>>;
+    rows: Array<Record<string, unknown>>;
+    data_ref: string;
+    truncated: boolean;
+    elapsed_ms: number;
+    applied_defaults?: string[];
+}
+export type CreateImportBody = {
+    upload_id: string;
+} | {
+    rows: unknown[];
+    dataset_id?: string;
+    mode?: "auto" | "append" | "new";
+    answers?: Record<string, string>;
+};
+export interface Tenant {
+    id: string;
+    contact_id: number;
+    display_name: string;
+    plan: string;
+    status: "active" | "suspended" | "deleted" | (string & {});
+    config?: Record<string, unknown>;
+    datasets?: string[];
+}
+export interface UpsertTenantBody {
+    contact_id: number;
+    display_name: string;
+    plan: string;
+    status?: string;
+    config?: Record<string, unknown>;
+    datasets?: string[];
+}
+export interface MintKeyBody {
+    class: "q" | "p" | "i";
+    name: string;
+    expires_in_s?: number;
+    allowed_origins?: string[];
+}
+export interface MintedKey {
+    key_id: string;
+    key_prefix: string;
+    /** Plaintext — returned by the platform exactly ONCE. Hand it to its destination and discard. */
+    key: string;
+}
+export interface TenantKeyMeta {
+    key_id: string;
+    key_prefix: string;
+    class?: string;
+    scopes?: string[];
+    expires_at?: string | null;
+}
+/** The `entities.resolve` job the tenant detail reports (null when none has ever run). */
+export interface ResolutionJobMeta {
+    job_id: string;
+    status: JobStatus | (string & {});
+    started_at: string | null;
+    finished_at: string | null;
+}
+/**
+ * Entity-layer fields arrive together once the platform deploys the layer (always present,
+ * 0/null, from then on). `people_named` doubles as the capability probe: `'people_named' in
+ * counts` → the layer exists.
+ */
+export interface TenantCounts {
+    sources: number;
+    chunks: number;
+    jobs_queued: number;
+    jobs_running: number;
+    storage_bytes: number;
+    people_named?: number;
+    people_unknown?: number;
+    aliases_pending?: number;
+    entities_place?: number;
+    entities_topic?: number;
+    last_resolution_at?: string | null;
+    resolution_job?: ResolutionJobMeta | null;
+}
+export interface TenantDetail {
+    tenant: Tenant;
+    keys?: TenantKeyMeta[];
+    counts?: TenantCounts;
+}
+export interface PurgeJob {
+    purge_job_id?: string;
+    tenant_id?: string;
+    state: "running" | "done" | "failed";
+    purged: {
+        pg: number | boolean;
+        meili: number | boolean;
+        media: number | boolean;
+        memory: number | boolean;
+    };
+    error?: string;
+    started_at?: string;
+    finished_at?: string;
+}
+export interface UsageRow {
+    tenant_id: string;
+    day: string;
+    kind: string;
+    quantity: number;
+    unit: string;
+    cost_usd: number;
+}
+/** Metadata-only source row — content fields are omitted by construction on the platform side. */
+export interface SourceMeta {
+    source_id: string;
+    kind: string;
+    title: string;
+    url?: string | null;
+    size_bytes?: number | null;
+    segments: number;
+    chunks: number;
+    indexed_chunks: number;
+    status: "indexing" | "ready" | "failed";
+    created_at: string;
+    updated_at: string;
+    tags?: string[];
+}
+export interface SourcesPage {
+    sources: SourceMeta[];
+    next_cursor: string | null;
+}
+/** `GET /v1/admin/tenants/:id/sources/summary` — whole-library counts in one call. */
+export interface SourceSummary {
+    total: number;
+    by_kind: Record<string, number>;
+    chunks: number;
+    indexed_chunks: number;
+    failed_sources: number;
+    last_indexed_at: string | null;
+}
+/** Job as GET /v1/ingest/jobs/:id plus the admin channel's dead-lettered webhook state. */
+export interface IngestJobMeta extends IngestJob {
+    webhook?: {
+        delivered: boolean;
+        dead: boolean;
+        attempts: number;
+    };
+}
+export interface AdminJobsPage {
+    jobs: IngestJobMeta[];
+    next_cursor: string | null;
+}
+export type CreateSourceBody = {
+    url: string;
+} | {
+    sitemap: string;
+    since?: string;
+} | {
+    upload_token: string;
+    kind?: IngestKind;
+    filename?: string;
+    options?: Record<string, unknown>;
+};
+export type PersonStatus = "named" | "unknown" | "hidden";
+export type EntityKind = "person" | "place" | "topic";
+/** One row of `GET …/people`. `display_name` is null for unnamed clusters; the handle is the
+ *  platform's opaque per-tenant label, never a name. */
+export interface PersonMeta {
+    person_id: string;
+    handle: string;
+    display_name: string | null;
+    status: PersonStatus;
+    face_count: number;
+    text_mentions: number;
+    docs: number;
+    aliases: number;
+    merged_into?: string | null;
+}
+export interface PeoplePage {
+    people: PersonMeta[];
+    next_cursor: string | null;
+}
+export interface PersonAlias {
+    alias: string;
+    alias_norm: string;
+    decided_by: "rule" | "embed" | "llm" | "human" | (string & {});
+    confidence: number | null;
+    mention_count: number;
+}
+export interface CoMention {
+    entity_id: string;
+    kind: EntityKind;
+    label: string;
+    shared_docs: number;
+}
+/** Witness document, metadata only (title/locator/url — never body text). */
+export interface EntityDocRef {
+    doc_id: string;
+    kind: string;
+    title: string;
+    locator: string;
+    url?: string | null;
+}
+export interface PersonDetail {
+    person: PersonMeta;
+    aliases: PersonAlias[];
+    co_mentions: CoMention[];
+    docs: EntityDocRef[];
+}
+export type PersonPatchBody = {
+    display_name: string;
+} | {
+    status: "hidden" | "unknown";
+};
+export interface MergeResult {
+    person_id: string;
+    into_person_id: string;
+    faces_moved: number;
+    aliases_moved: number;
+    merge_id: number | string;
+    job_id: string | null;
+}
+export interface AliasSuggestion {
+    kind: EntityKind;
+    alias: string;
+    alias_norm: string;
+    status?: "pending" | "accepted" | "rejected";
+    mention_count: number;
+    sample_docs: Array<{
+        doc_id: string;
+        title: string;
+        locator: string;
+    }>;
+    suggested_entity_id?: string | null;
+    suggested_label?: string | null;
+    confidence: number | null;
+    decided_by: string | null;
+    rationale?: string | null;
+}
+export interface AliasesPage {
+    aliases: AliasSuggestion[];
+    next_cursor: string | null;
+}
+/** Alias identity is (kind, alias_norm) — there is no alias_id. */
+export interface AliasDecisionBody {
+    kind: EntityKind;
+    alias_norm: string;
+    decision: "accept" | "reject";
+    entity_id?: string;
+    create_person?: {
+        display_name: string;
+    };
+}
+export interface LiveSourceTotals {
+    total: number;
+    failed: number;
+    /** only when the platform served the summary route */
+    by_kind?: Record<string, number>;
+    /** the paged fallback stopped at its cap — total is a floor, not a count */
+    truncated: boolean;
+}

package/dist/esm/types.js

@@ -0,0 +1,3 @@
+// Shapes from docs/api-v1.md. Additive changes only — anything breaking goes to /v2.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,qFAAqF"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@awesomate/platform-sdk",
+  "version": "0.1.0",
+  "description": "Typed client for the Awesomate platform /v1 API — tenant API (answer, query, media, ingest, data) and the hub service channel. Browser + Node, no dependencies.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/itmooti/platform.git",
+    "directory": "packages/sdk"
+  },
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "typescript": "5.9.2",
+    "vitest": "4.1.11"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "lint": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  }
+}