@awesomate/platform-sdk 0.1.0

package/dist/cjs/sse.js.map

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

package/dist/cjs/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/cjs/types.js

@@ -0,0 +1,4 @@
+"use strict";
+// Shapes from docs/api-v1.md. Additive changes only — anything breaking goes to /v2.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/types.js.map

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

package/dist/esm/client.d.ts

@@ -0,0 +1,128 @@
+import type { FetchLike } from "./http.js";
+import type { CollectedAnswer } from "./sse.js";
+import type { Answer, AnswerRequest, AnswerStreamEvent, CompleteUploadBody, CreateImportBody, CreateJobBody, CreateUploadBody, DataQuery, DataQueryResult, DatasetSummary, Enqueued, Feedback, IngestJob, JobsPage, KeyClass, PlatformResult, QueryParams, QueryResponse, Status, UploadTicket, Whoami } from "./types.js";
+export interface PlatformClientConfig {
+    /** Tenant API base, e.g. `https://knowledge.awesomate.ai` (dev: `https://api.dev.awesomate.dev`). */
+    baseUrl: string;
+    /** A tenant key: `amk_q_` (server), `amk_p_` (browser, origin-locked), `amk_i_` (ingest), `amk_u_` (user token). */
+    apiKey: string;
+    /** Control-plane budget; answers and uploads have their own. Default 10 s. */
+    timeoutMs?: number;
+    /** Long-running answer budget. Default 5 min. */
+    answerTimeoutMs?: number;
+    /** Byte-upload budget. Default 10 min. */
+    uploadTimeoutMs?: number;
+    fetchImpl?: FetchLike;
+}
+export type AnswerStreamResult = {
+    ok: true;
+    status: number;
+    contentType: string;
+    /** The raw SSE body — pipe it straight through to your own response. */
+    body: ReadableStream<Uint8Array>;
+    /** Typed events over the same body; consume either `body` or `events()`, not both. */
+    events: () => AsyncGenerator<AnswerStreamEvent>;
+    /** Drain to the final text + meta. */
+    collect: () => Promise<CollectedAnswer>;
+} | Exclude<PlatformResult<never>, {
+    ok: true;
+}>;
+/** Class of a platform key, or null when the string is not a well-formed key. */
+export declare function keyClass(key: string): KeyClass | null;
+/**
+ * Client for the tenant API (`/v1/*`). One instance = one key = one tenant; the platform
+ * scopes every call server-side. Never throws on the request path — see PlatformResult.
+ */
+export declare class PlatformClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly answerTimeoutMs;
+    private readonly uploadTimeoutMs;
+    private readonly fetchImpl;
+    constructor(config: PlatformClientConfig);
+    isConfigured(): boolean;
+    private headers;
+    private request;
+    /** `POST /v1/answer`, JSON: the validated answer with numbered sources. */
+    answer(body: AnswerRequest, opts?: {
+        signal?: AbortSignal;
+    }): Promise<PlatformResult<Answer>>;
+    /** `POST /v1/answer` with `Accept: text/event-stream`: sources first, then gated sentences, then meta. */
+    answerStream(body: AnswerRequest, opts?: {
+        signal?: AbortSignal;
+    }): Promise<AnswerStreamResult>;
+    /** v2 `POST /v1/agents/:agent_id/chat` streamed (Phase 1; `404 not_found` until it lands). */
+    agentChatStream(agentId: string, body: {
+        message: string;
+        session_id?: string;
+        include_media?: boolean;
+        metadata?: Record<string, unknown>;
+    }, opts?: {
+        signal?: AbortSignal;
+    }): Promise<AnswerStreamResult>;
+    private stream;
+    /** `GET /v1/query` — raw hybrid-search passages (bypass the citation gate). */
+    query(params: QueryParams, opts?: {
+        signal?: AbortSignal;
+    }): Promise<PlatformResult<QueryResponse>>;
+    whoami(): Promise<PlatformResult<Whoami>>;
+    status(): Promise<PlatformResult<Status>>;
+    feedback(body: Feedback): Promise<PlatformResult<void>>;
+    /**
+     * `GET /v1/media/<key>`: the platform 302s to a 10-minute presigned URL. `fetch` follows
+     * it, so the Response carries the bytes. Prefer presigned URLs from answer sources where
+     * the platform supplies them; use this when you hold only a media key.
+     */
+    media(key: string, init?: {
+        range?: string;
+        signal?: AbortSignal;
+    }): Promise<PlatformResult<Response>>;
+    createUpload(body: CreateUploadBody): Promise<PlatformResult<UploadTicket>>;
+    completeUpload(uploadId: string, body?: CompleteUploadBody): Promise<PlatformResult<{
+        upload_id: string;
+        status: string;
+    }>>;
+    /**
+     * PUT the staged bytes to `put_url` EXACTLY as the platform returned it. A presigned S3 URL
+     * is its own credential and gets no headers of ours. On FsStore deployments the platform
+     * hands back its own `/v1/ingest/uploads/:id/content` route instead, which sits behind the
+     * same ingest-key auth as every `/v1/ingest/*` call, so that one carries the Bearer key.
+     * A relative `put_url` resolves against `baseUrl`.
+     */
+    uploadBytes(putUrl: string, body: BodyInit | ReadableStream<Uint8Array>, sizeBytes?: number): Promise<PlatformResult<void>>;
+    /** `POST /v1/ingest/jobs`; pass `idempotencyKey` so a retry returns the same job. */
+    createJob(body: CreateJobBody, opts?: {
+        idempotencyKey?: string;
+    }): Promise<PlatformResult<Enqueued>>;
+    getJob(jobId: string): Promise<PlatformResult<IngestJob>>;
+    listJobs(params?: {
+        status?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<PlatformResult<JobsPage>>;
+    cancelJob(jobId: string): Promise<PlatformResult<{
+        job_id: string;
+        status: string;
+    }>>;
+    retryJob(jobId: string): Promise<PlatformResult<Enqueued>>;
+    listDatasets(): Promise<PlatformResult<{
+        datasets: DatasetSummary[];
+    }>>;
+    getDataset(datasetId: string): Promise<PlatformResult<DatasetSummary & Record<string, unknown>>>;
+    queryData(dsl: DataQuery, opts?: {
+        signal?: AbortSignal;
+    }): Promise<PlatformResult<DataQueryResult>>;
+    createImport(body: CreateImportBody, opts?: {
+        idempotencyKey?: string;
+    }): Promise<PlatformResult<Enqueued & {
+        import_id: string | null;
+    }>>;
+    getImport(id: string): Promise<PlatformResult<Record<string, unknown>>>;
+}
+/**
+ * Shared by the tenant and service clients: a PUT of raw bytes to the platform's `put_url`.
+ * `headers` is empty for presigned URLs (the URL is the credential) and carries the Bearer
+ * key only for the platform's own auth-gated upload route.
+ */
+export declare function uploadTo(fetchImpl: FetchLike, url: string, body: BodyInit | ReadableStream<Uint8Array>, sizeBytes: number | undefined, timeoutMs: number, headers?: Record<string, string>): Promise<PlatformResult<void>>;