@keelapi/sdk 0.1.0

package/dist/src/streaming.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSSEStream = parseSSEStream;
+async function* parseSSEStream(response) {
+    const reader = response.body?.getReader();
+    if (!reader) {
+        return;
+    }
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let currentEvent = "message";
+    let dataLines = [];
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const rawLine of lines) {
+                const line = rawLine.replace(/\r$/, "");
+                if (line === "") {
+                    if (dataLines.length > 0) {
+                        const sse = {
+                            event: currentEvent,
+                            data: dataLines.join("\n"),
+                        };
+                        yield decodeSSEEvent(sse);
+                        dataLines = [];
+                        currentEvent = "message";
+                    }
+                    continue;
+                }
+                if (line.startsWith(":")) {
+                    continue;
+                }
+                if (line.startsWith("event:")) {
+                    currentEvent = line.slice(6).trimStart();
+                }
+                else if (line.startsWith("data:")) {
+                    dataLines.push(line.slice(5).trimStart());
+                }
+            }
+        }
+        if (dataLines.length > 0) {
+            const sse = {
+                event: currentEvent,
+                data: dataLines.join("\n"),
+            };
+            yield decodeSSEEvent(sse);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function decodeSSEEvent(sse) {
+    let data;
+    try {
+        data = JSON.parse(sse.data);
+    }
+    catch {
+        return { event: sse.event, data: sse.data };
+    }
+    switch (sse.event) {
+        case "execution.started":
+            return { event: "execution.started", data };
+        case "content.delta":
+            return { event: "content.delta", data };
+        case "execution.completed":
+            return { event: "execution.completed", data };
+        case "execution.denied":
+            return { event: "execution.denied", data };
+        case "execution.error":
+            return { event: "execution.error", data };
+        case "done":
+            return { event: "done", data };
+        default:
+            return { event: sse.event, data };
+    }
+}

package/dist/src/types.d.ts

@@ -0,0 +1,622 @@
+export type Decision = "allow" | "deny" | "challenge";
+export type ExecutionOperation = "generate.text" | "embed.text" | "generate.image" | "edit.image" | "understand.image" | "generate.audio" | "transcribe.audio" | "generate.video" | "understand.video" | "run.batch" | "run.async" | "realtime.session" | "call.tools";
+export type ExecutionMode = "sync" | "stream";
+export type ExecutionRole = "system" | "user" | "assistant";
+export type ExecutionAssetSource = "url" | "upload" | "base64" | "asset_ref";
+export type ExecutionInputType = "text" | "json" | "image" | "audio" | "video" | "file" | "binary";
+export type RoutingProvider = "openai" | "anthropic" | "google" | "xai" | "meta";
+export type RoutingPriority = "cheap" | "balanced" | "quality";
+export type RoutingReasonCode = "explicit_request" | "policy_preference" | "cost_optimization" | "quality_preference" | "routing_fitness" | "fallback_after_error";
+export type JobStatus = "submitted" | "queued" | "processing" | "completed" | "failed";
+export type PermitExportFormat = "json" | "csv";
+export type PermitDryRunReplayOutcome = "fresh" | "would_reuse_existing" | "would_revalidate_existing" | "would_expire_existing";
+export type ConditionMatch = "all" | "any";
+export type ConditionOutcome = "allow" | "deny" | "indeterminate";
+export interface Subject {
+    type: string;
+    id: string;
+    attributes?: Record<string, unknown>;
+}
+export interface Action {
+    name: string;
+    attributes?: Record<string, unknown>;
+}
+export interface InputDescriptor {
+    type: string;
+    source?: string;
+    url?: string;
+    filename?: string;
+    mime_type?: string;
+    size_bytes?: number;
+    sha256?: string;
+    asset_id?: string;
+    base64_data?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ResourceAttributes {
+    provider: string;
+    model: string;
+    estimated_input_tokens: number;
+    estimated_output_tokens: number;
+    max_output_tokens_requested?: number | null;
+    operation?: string;
+    modality?: string;
+    execution_mode?: "sync" | "async";
+    inputs?: InputDescriptor[];
+    routing?: Record<string, unknown>;
+    callback_url?: string;
+    asset_summary?: Record<string, unknown>;
+}
+export interface Resource {
+    type: string;
+    id: string;
+    attributes: ResourceAttributes;
+}
+export interface PermitConditionRule {
+    field: string;
+    operator: string;
+    value?: unknown;
+}
+export interface PermitConditions {
+    match: ConditionMatch;
+    rules: PermitConditionRule[];
+}
+export interface PermitRequest {
+    project_id: string;
+    idempotency_key: string;
+    session_id?: string | null;
+    subject: Subject;
+    action: Action;
+    resource: Resource;
+    context?: Record<string, unknown> | null;
+    parent_permit_id?: string | null;
+    budget_envelope_id?: string | null;
+    conditions?: PermitConditions | null;
+}
+export interface ActionMessage {
+    type: string;
+    message: string;
+}
+export interface Metadata {
+    policy_id: string;
+    policy_version: string;
+    evaluated_at: string;
+    subject?: {
+        type: string;
+        id: string;
+    } | null;
+    action?: {
+        name: string;
+    } | null;
+    session_id?: string | null;
+}
+export interface DecisionDetails {
+    decision: string;
+    code: string;
+    reason: string;
+    [key: string]: unknown;
+}
+export interface RoutingTarget {
+    provider: RoutingProvider;
+    model: string;
+}
+export interface RoutingDecision {
+    decision_id: string;
+    decided_at: string;
+    requested_provider: RoutingProvider;
+    requested_model: string;
+    selected_provider: RoutingProvider;
+    selected_model: string;
+    reason_code: RoutingReasonCode;
+    fallback_occurred: boolean;
+    policy_id?: string | null;
+    policy_version?: string | null;
+    estimated_cost_usd_micros?: number | null;
+    priority?: RoutingPriority | null;
+    task_type?: string | null;
+    latency_target_ms?: number | null;
+    fallback_chain?: RoutingTarget[];
+    reason_metadata?: Record<string, unknown> | null;
+}
+export interface PermitResponse {
+    permit_id: string;
+    project_id: string;
+    decision: Decision;
+    reason: string;
+    constraints?: Record<string, unknown> | null;
+    budgets?: Record<string, unknown> | null;
+    actions: ActionMessage[];
+    metadata: Metadata;
+    parent_permit_id?: string | null;
+    delegation_depth?: number;
+    status?: string | null;
+    decision_details?: DecisionDetails | null;
+    routing?: RoutingDecision | null;
+}
+export interface PermitWithMetaResponse {
+    permit: PermitResponse;
+    request_id?: string;
+}
+export interface BudgetEnvelopeSummary {
+    envelope_id: string;
+    reservation_status?: string | null;
+    estimated_cost_usd_micros?: number | null;
+    total_budget_usd_micros?: number | null;
+    reserved_budget_usd_micros?: number | null;
+    spent_budget_usd_micros?: number | null;
+    remaining_budget_usd_micros?: number | null;
+    correction_usd_micros?: number | null;
+}
+export interface ConditionEvaluation {
+    outcome: ConditionOutcome;
+    evaluated_at: string;
+    match: ConditionMatch;
+    rule_count: number;
+    failed_rule_index?: number | null;
+    code?: string | null;
+    message?: string | null;
+    field?: string | null;
+    operator?: string | null;
+    expected_value?: unknown;
+    actual_value?: unknown;
+}
+export interface PermitDryRunResponse {
+    dry_run: true;
+    project_id: string;
+    existing_permit_id?: string | null;
+    replay_outcome: PermitDryRunReplayOutcome;
+    parent_permit_id?: string | null;
+    delegation_depth?: number;
+    decision: Decision;
+    reason: string;
+    status?: string | null;
+    constraints?: Record<string, unknown> | null;
+    budgets?: Record<string, unknown> | null;
+    actions: ActionMessage[];
+    decision_details?: DecisionDetails | null;
+    routing?: RoutingDecision | null;
+    metadata: Metadata;
+    budget_envelope?: BudgetEnvelopeSummary | null;
+    condition_evaluation?: ConditionEvaluation | null;
+}
+export interface PermitAuditItem {
+    id: string;
+    project_id: string;
+    parent_permit_id?: string | null;
+    delegation_depth?: number;
+    subject_type: string;
+    subject_id: string;
+    action_name: string;
+    resource_provider: string;
+    resource_model: string;
+    resource_operation?: string | null;
+    resource_modality?: string | null;
+    resource_inputs_json?: Array<Record<string, unknown>> | null;
+    resource_attributes_json?: Record<string, unknown> | null;
+    estimated_input_tokens: number;
+    estimated_output_tokens: number;
+    max_output_tokens_requested?: number | null;
+    decision: Decision;
+    reason: string;
+    status?: string | null;
+    constraints_json?: Record<string, unknown> | null;
+    budgets_json?: Record<string, unknown> | null;
+    budget_envelope?: BudgetEnvelopeSummary | null;
+    actions_json: Array<Record<string, unknown>>;
+    conditions?: PermitConditions | null;
+    condition_evaluation?: ConditionEvaluation | null;
+    decision_details?: DecisionDetails | null;
+    routing?: RoutingDecision | null;
+    actual_usage_json?: Record<string, unknown> | null;
+    policy_id: string;
+    policy_version: string;
+    metadata: Metadata;
+    idempotency_key: string;
+    request_fingerprint: string;
+    expires_at?: string | null;
+    created_at: string;
+}
+export interface PermitAuditListResponse {
+    items: PermitAuditItem[];
+    next_cursor: string | null;
+}
+export interface PermitListParams {
+    limit?: number;
+    project_id?: string;
+    before?: string;
+    subject_id?: string;
+    subject_type?: string;
+    action_name?: string;
+    start_date?: string;
+    end_date?: string;
+    decision?: Decision;
+}
+export interface PermitUsageReportRequest {
+    provider?: string | null;
+    model?: string | null;
+    actual_input_tokens?: number | null;
+    actual_output_tokens?: number | null;
+    actual_total_tokens?: number | null;
+    cost_usd?: string | number | null;
+    cost_usd_micros?: number | null;
+    usage_idempotency_key?: string | null;
+    normalized_usage?: Record<string, number> | null;
+    usage_metrics?: Array<Record<string, unknown>> | null;
+    metadata?: Record<string, unknown> | null;
+}
+export interface PermitUsageReportResponse {
+    permit_id: string;
+    project_id: string;
+    usage_reported_at?: string | null;
+    actual_input_tokens?: number | null;
+    actual_output_tokens?: number | null;
+    actual_total_tokens?: number | null;
+    actual_cost_usd_micros?: number | null;
+    actual_usage_json?: Record<string, unknown> | null;
+    status?: string | null;
+}
+export interface PermitAttestationRequest {
+    attestor: string;
+    attestation_type: "approve" | "reject";
+    evidence_url?: string | null;
+}
+export interface PermitAttestationOut {
+    id: string;
+    permit_id: string;
+    project_id: string;
+    attestor: string;
+    attestation_type: "approve" | "reject";
+    evidence_url?: string | null;
+    attested_at: string;
+    created_at: string;
+}
+export interface PermitAttestResponse {
+    permit: PermitResponse;
+    attestation: PermitAttestationOut;
+}
+export interface PermitEvidenceCreateRequest {
+    evidence_type: string;
+    evidence_value: string;
+    label: string;
+    attached_by: string;
+}
+export interface PermitEvidenceOut {
+    id: string;
+    permit_id: string;
+    project_id: string;
+    evidence_type: string;
+    evidence_value: string;
+    label: string;
+    attached_by: string;
+    attached_at: string;
+}
+export interface PermitEvidenceListResponse {
+    items: PermitEvidenceOut[];
+}
+export interface PermitLineageNodeSummary {
+    permit_id: string;
+    parent_permit_id?: string | null;
+    delegation_depth: number;
+    decision: Decision;
+    status?: string | null;
+    reason: string;
+    action_name: string;
+    resource_provider: string;
+    resource_model: string;
+    created_at: string;
+    expires_at?: string | null;
+    usage_reported_at?: string | null;
+    actual_total_tokens?: number | null;
+    actual_cost_usd_micros?: number | null;
+}
+export interface PermitLineageNode extends PermitLineageNodeSummary {
+    children: PermitLineageNode[];
+}
+export interface PermitLineageResponse {
+    project_id: string;
+    root_permit_id: string;
+    current_permit_id: string;
+    parent?: PermitLineageNodeSummary | null;
+    ancestors: PermitLineageNodeSummary[];
+    current: PermitLineageNode;
+}
+export interface PermitAuditBundle {
+    bundle_type: "permit_audit_bundle";
+    schema_version: number;
+    format: "json";
+    project_id: string;
+    permit_id: string;
+    generated_at: string;
+    record: Record<string, unknown>;
+    governance_events: Array<Record<string, unknown>>;
+}
+export interface ApiKey {
+    id: string;
+    project_id: string;
+    prefix: string;
+    created_at: string;
+    revoked_at: string | null;
+}
+export interface CreateApiKeyResponse extends ApiKey {
+    raw_key: string;
+    request_id?: string;
+}
+export interface ListApiKeysResponse {
+    items: ApiKey[];
+    request_id?: string;
+}
+export interface RevokeApiKeyResponse extends ApiKey {
+    request_id?: string;
+}
+export interface HealthResponse {
+    status: "ok";
+    request_id?: string;
+}
+export interface AuthedHealthResponse extends HealthResponse {
+    project_id: string;
+}
+export interface ExecutionMessage {
+    role: ExecutionRole;
+    content: string;
+}
+export interface ExecutionAssetInput {
+    source: ExecutionAssetSource;
+    url?: string;
+    asset_id?: string;
+    base64?: string;
+    mime_type?: string;
+    filename?: string;
+    size_bytes?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface ExecutionInputPart {
+    type: ExecutionInputType;
+    role?: ExecutionRole;
+    text?: string;
+    json?: Record<string, unknown>;
+    asset?: ExecutionAssetInput;
+    metadata?: Record<string, unknown>;
+}
+export interface ExecutionRoutingTarget {
+    provider: RoutingProvider;
+    model: string;
+}
+export interface ExecutionRoutingInput {
+    provider?: RoutingProvider;
+    model?: string;
+    priority?: RoutingPriority;
+    task_type?: string;
+    latency_target_ms?: number;
+    allow_cross_provider_fallback?: boolean;
+    fallback_chain?: ExecutionRoutingTarget[];
+}
+export interface ExecutionParametersInput {
+    max_output_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+}
+export type ExecutionProviderOptions = Partial<Record<RoutingProvider, Record<string, unknown>>>;
+export interface ExecutionCreateRequest {
+    operation: ExecutionOperation;
+    mode?: ExecutionMode;
+    messages?: ExecutionMessage[];
+    inputs?: ExecutionInputPart[];
+    routing?: ExecutionRoutingInput;
+    parameters?: ExecutionParametersInput;
+    provider_options?: ExecutionProviderOptions;
+}
+export interface ExecuteRequest {
+    provider?: RoutingProvider;
+    model: string;
+    input: Record<string, unknown>;
+}
+export interface ExecutionOutputContentPart {
+    type: string;
+    role?: string;
+    text?: string;
+    [key: string]: unknown;
+}
+export interface ExecutionOutput {
+    content?: ExecutionOutputContentPart[];
+    embeddings?: unknown[];
+    raw?: Record<string, unknown>;
+}
+export interface ExecutionOutputAsset {
+    asset_id: string;
+    type: string;
+    mime_type: string;
+    size_bytes?: number | null;
+    uri?: string | null;
+    status?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface ExecutionRoutingResult {
+    requested_provider?: RoutingProvider | null;
+    requested_model?: string | null;
+    selected_provider: RoutingProvider;
+    selected_model: string;
+    reason_code: string;
+    fallback_occurred: boolean;
+}
+export interface ExecutionGovernance {
+    decision: Decision;
+    reason: string;
+    actions: ActionMessage[];
+    constraints?: Record<string, unknown> | null;
+    budgets?: Record<string, unknown> | null;
+}
+export interface ExecutionUsage {
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    total_tokens?: number | null;
+    cost_usd_micros?: number | null;
+    estimated_final?: boolean;
+    metrics?: Array<Record<string, unknown>> | null;
+}
+export interface ExecutionTiming {
+    started_at?: string | null;
+    completed_at?: string | null;
+    duration_ms?: number | null;
+}
+export interface ExecutionErrorPayload {
+    stage?: string;
+    code: string;
+    message: string;
+    details?: Record<string, unknown> | null;
+    retry_class?: string | null;
+    status_code?: number | null;
+}
+export interface ExecutionResolved {
+    provider?: string;
+    model?: string;
+}
+export interface ExecutionResponse {
+    id: string;
+    object: "execution";
+    created_at: string | null;
+    status: "completed" | "in_progress" | "failed" | "denied";
+    status_code: number;
+    output?: ExecutionOutput | null;
+    output_assets: ExecutionOutputAsset[];
+    routing: ExecutionRoutingResult;
+    governance?: ExecutionGovernance | null;
+    usage?: ExecutionUsage | null;
+    timing: ExecutionTiming;
+    error?: ExecutionErrorPayload | null;
+    resolved?: ExecutionResolved | null;
+}
+export type ExecutionStreamEventName = "execution.started" | "content.delta" | "execution.completed" | "execution.denied" | "execution.error" | "done";
+export interface ExecutionStartedEvent {
+    event: "execution.started";
+    data: {
+        id: string;
+        object: "execution";
+        created_at: string | null;
+        status: string;
+        status_code: number;
+        routing?: ExecutionRoutingResult | null;
+        governance?: ExecutionGovernance | null;
+    };
+}
+export interface ExecutionContentDelta {
+    event: "content.delta";
+    data: {
+        id: string;
+        object: "execution";
+        created_at: string | null;
+        delta: {
+            type: string;
+            text?: string;
+        };
+    };
+}
+export interface ExecutionCompletedEvent {
+    event: "execution.completed";
+    data: ExecutionResponse;
+}
+export interface ExecutionDeniedEvent {
+    event: "execution.denied";
+    data: ExecutionResponse;
+}
+export interface ExecutionErrorEvent {
+    event: "execution.error";
+    data: ExecutionResponse;
+}
+export interface ExecutionDoneEvent {
+    event: "done";
+    data: {
+        id: string;
+        object: "execution";
+    };
+}
+export interface ExecutionRawEvent {
+    event: string;
+    data: unknown;
+}
+export type ExecutionStreamEvent = ExecutionStartedEvent | ExecutionContentDelta | ExecutionCompletedEvent | ExecutionDeniedEvent | ExecutionErrorEvent | ExecutionDoneEvent | ExecutionRawEvent;
+export interface JobSubmitRequest {
+    permit: PermitRequest;
+    provider_payload?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+export interface JobCreateResponse {
+    job_id: string;
+    status: JobStatus;
+    execution_mode: "async";
+    submitted_at: string;
+    permit_id?: string | null;
+}
+export interface JobStatusResponse {
+    job_id: string;
+    request_id: string;
+    permit_id?: string | null;
+    provider: string;
+    model: string;
+    operation: string;
+    execution_mode: "async";
+    status: JobStatus;
+    progress?: number | null;
+    callback_url?: string | null;
+    submitted_at: string;
+    started_at?: string | null;
+    completed_at?: string | null;
+    result_assets?: Array<Record<string, unknown>> | null;
+    usage_metrics?: Array<Record<string, unknown>> | null;
+    error?: Record<string, unknown> | null;
+    metadata?: Record<string, unknown> | null;
+}
+export type RequestTimelineEventSource = "permits" | "usage_ledger" | "usage_logs" | "governed_requests" | "execution_events" | "async_jobs" | "realtime_sessions";
+export type RequestTimelinePhase = "permit" | "routing" | "firewall" | "execution" | "provider" | "usage" | "request" | "job" | "session" | "webhook";
+export interface RequestTimelineEvent {
+    timestamp: string;
+    event_type: string;
+    source: RequestTimelineEventSource;
+    phase: RequestTimelinePhase;
+    provider?: string | null;
+    model?: string | null;
+    permit_id?: string | null;
+    request_id?: string | null;
+    job_id?: string | null;
+    session_id?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+export interface RequestTimelineResponse {
+    project_id: string;
+    request_id: string;
+    permit_ids: string[];
+    job_ids: string[];
+    session_ids: string[];
+    events: RequestTimelineEvent[];
+}
+export interface ExecutionTimelinePermit {
+    decision?: string | null;
+    timestamp?: string | null;
+}
+export interface ExecutionTimelineRouting {
+    provider?: string | null;
+    model?: string | null;
+    fallback_chain?: RoutingTarget[] | null;
+}
+export interface ExecutionTimelineQueue {
+    job_id?: string | null;
+    status?: string | null;
+    attempts?: number | null;
+}
+export interface ExecutionTimelineExecution {
+    started_at?: string | null;
+    completed_at?: string | null;
+    latency_ms?: number | null;
+}
+export interface ExecutionTimelineUsage {
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    cost_usd?: number | null;
+}
+export interface ExecutionTimelineResponse {
+    request_id: string;
+    permit: ExecutionTimelinePermit;
+    routing: ExecutionTimelineRouting;
+    queue: ExecutionTimelineQueue;
+    execution: ExecutionTimelineExecution;
+    usage: ExecutionTimelineUsage;
+}

package/dist/src/types.js

@@ -0,0 +1,5 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Shared literals
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });