@astrogate/sdk 0.0.0-stage → 0.1.0-rc.1

package/dist/operator.js

@@ -0,0 +1,53 @@
+// Server-only read surface. Product credentials and app-use sessions cannot
+// authenticate here. Issuance and mutation remain installation-owned.
+import { identifier, managementAuthority, object, requestJSON, } from "./http.js";
+import { project, environment, placementState, operation, operationLog, operatorOperationDetail, buildingBlock, hostnameBinding } from "./management-read.js";
+import { listQuery, pageOf } from "./inventory.js";
+export { AstrogateError } from "./http.js";
+function catalogEntry(value) {
+    return object(value) && typeof value.id === "string";
+}
+function environmentTopology(value) {
+    if (!object(value) || typeof value.cell !== "string" || !Number.isSafeInteger(value.epoch) || typeof value.fresh !== "boolean" || typeof value.observedAt !== "string" || typeof value.validUntil !== "string" || !Number.isFinite(Date.parse(value.observedAt)) || !Number.isFinite(Date.parse(value.validUntil)))
+        return false;
+    return Array.isArray(value.hosts) && value.hosts.every(host => object(host) && typeof host.ready === "boolean" && ["name", "providerId", "architecture", "operatingSystem", "kubeletVersion", "containerRuntimeVersion"].every(key => typeof host[key] === "string")) && Array.isArray(value.targets) && value.targets.every(target => object(target) && typeof target.ready === "boolean" && ["name", "node", "service"].every(key => typeof target[key] === "string"));
+}
+export function createOperator(options) {
+    const endpoint = managementAuthority(options);
+    function read(path, validate, signal) {
+        return requestJSON(new URL(`/v1/operator/products${path}`, endpoint), options, { method: "GET", headers: { authorization: `Bearer ${options.token}` } }, validate, signal);
+    }
+    const scope = (product, tenant) => `/${identifier(product)}/tenants/${identifier(tenant)}`;
+    const projectPath = (product, tenant, id) => `${scope(product, tenant)}/projects/${identifier(id)}`;
+    const environmentPath = (product, tenant, project, id) => `${projectPath(product, tenant, project)}/environments/${identifier(id)}`;
+    return {
+        products: {
+            list: (page = {}, signal) => read(listQuery(page), pageOf(catalogEntry), signal),
+        },
+        tenants: {
+            list: (product, page = {}, signal) => read(`/${identifier(product)}/tenants${listQuery(page)}`, pageOf(catalogEntry), signal),
+        },
+        projects: {
+            list: (product, tenant, page = {}, signal) => read(`${scope(product, tenant)}/projects${listQuery(page)}`, pageOf(project), signal),
+            get: (product, tenant, id, signal) => read(projectPath(product, tenant, id), project, signal),
+        },
+        buildingBlocks: {
+            list: (product, tenant, project, environment, page = {}, signal) => read(`${environmentPath(product, tenant, project, environment)}/building-blocks${listQuery(page)}`, pageOf(buildingBlock), signal),
+            get: (product, tenant, project, environment, id, signal) => read(`${environmentPath(product, tenant, project, environment)}/building-blocks/${identifier(id)}`, buildingBlock, signal),
+        },
+        hostnames: {
+            list: (product, tenant, project, environment, page = {}, signal) => read(`${environmentPath(product, tenant, project, environment)}/hostnames${listQuery(page)}`, pageOf(hostnameBinding), signal),
+        },
+        operations: {
+            list: (product, tenant, project, page = {}, signal) => read(`${projectPath(product, tenant, project)}/operations${listQuery(page)}`, pageOf(operation), signal),
+            get: (product, tenant, project, id, signal) => read(`${projectPath(product, tenant, project)}/operations/${identifier(id)}`, operatorOperationDetail, signal),
+            logs: (product, tenant, project, id, kind, signal) => read(`${projectPath(product, tenant, project)}/operations/${identifier(id)}/logs/${identifier(kind)}`, operationLog, signal),
+        },
+        environments: {
+            getTopology: (product, tenant, project, id, signal) => read(`${environmentPath(product, tenant, project, id)}/topology`, environmentTopology, signal),
+            list: (product, tenant, project, page = {}, signal) => read(`${projectPath(product, tenant, project)}/environments${listQuery(page)}`, pageOf(environment), signal),
+            get: (product, tenant, project, id, signal) => read(environmentPath(product, tenant, project, id), environment, signal),
+            getPlacement: (product, tenant, project, id, signal) => read(`${environmentPath(product, tenant, project, id)}/placement`, placementState, signal),
+        },
+    };
+}

package/dist/react.d.ts

@@ -0,0 +1,16 @@
+import { init } from "@instantdb/react";
+import { type DatabaseBinding } from "./database-binding.js";
+export { i, id, lookup } from "@instantdb/core";
+export type * from "@instantdb/react";
+export { createAuthClient } from "better-auth/react";
+type NativeSchema = NonNullable<Parameters<typeof init>[0]["schema"]>;
+export declare function createClient<Schema extends NativeSchema, Dates extends boolean = false>(options: {
+    binding: DatabaseBinding;
+    schema: Schema;
+    useDateObjects?: Dates;
+}): {
+    db: import("@instantdb/react").InstantReactWebDatabase<Schema, Dates, import("@instantdb/core").InstantConfig<Schema, Dates>>;
+};
+export { getHostedDatabaseSession } from "./hosted-session.js";
+export { createApplication, createStorageClient, AstrogateError } from "./browser.js";
+export type { ServiceBinding, ServiceBindings, StorageObject, CreateStorageUpload, StorageOptions } from "./browser.js";

package/dist/react.js

@@ -0,0 +1,10 @@
+import { init } from "@instantdb/react";
+import { databaseEndpoint } from "./database-binding.js";
+export { i, id, lookup } from "@instantdb/core";
+export { createAuthClient } from "better-auth/react";
+export function createClient(options) {
+    const db = init({ ...databaseEndpoint(options.binding), schema: options.schema, useDateObjects: options.useDateObjects });
+    return { db };
+}
+export { getHostedDatabaseSession } from "./hosted-session.js";
+export { createApplication, createStorageClient, AstrogateError } from "./browser.js";

package/dist/server.d.ts

@@ -0,0 +1,27 @@
+import { init } from "@instantdb/admin";
+import { type DatabaseBinding } from "./database-binding.js";
+export { i, id, lookup } from "@instantdb/core";
+export type * from "@instantdb/admin";
+export { betterAuth } from "better-auth";
+type NativeSchema = NonNullable<Parameters<typeof init>[0]["schema"]>;
+export declare function createClient<Schema extends NativeSchema, Dates extends boolean = false>(options: {
+    binding: DatabaseBinding;
+    schema: Schema;
+    sessionToken: string;
+    useDateObjects?: Dates;
+}): {
+    db: import("@instantdb/admin").InstantAdminDatabase<Schema, Dates, import("@instantdb/admin").InstantConfig<Schema, Dates>>;
+};
+export declare function exchangeDatabaseSession(options: {
+    binding: DatabaseBinding;
+    cookie: string;
+    issuerCredential: string;
+    signal: AbortSignal;
+}): Promise<string>;
+export { createStorageClient } from "./storage.js";
+export { createJobsClient } from "./tasks.js";
+export type { TaskDefinition, TaskContext, JobRunState } from "./tasks.js";
+export type { StorageObject, CreateStorageUpload, StorageOptions } from "./storage.js";
+export type { ServiceBinding, ServiceBindings, ServiceSessions } from "./services.js";
+export { serviceSessionsFromHeader } from "./services.js";
+export { AstrogateError } from "./http.js";

package/dist/server.js

@@ -0,0 +1,30 @@
+import { init } from "@instantdb/admin";
+import { databaseEndpoint } from "./database-binding.js";
+export { i, id, lookup } from "@instantdb/core";
+export { betterAuth } from "better-auth";
+export function createClient(options) {
+    if (!options.sessionToken)
+        throw new Error("A scoped application session is required");
+    const db = init({ ...databaseEndpoint(options.binding), schema: options.schema, useDateObjects: options.useDateObjects, adminToken: options.sessionToken }).asUser({ token: options.sessionToken });
+    return { db };
+}
+// Call from an application's own authenticated server route. Its cookies need
+// not cover the infrastructure domain, and the issuer credential stays server-side.
+export async function exchangeDatabaseSession(options) {
+    if (typeof window !== "undefined")
+        throw new Error("Database session exchange is server-only");
+    const endpoint = databaseEndpoint(options.binding);
+    const origin = new URL(endpoint.apiURI);
+    const request = { appId: endpoint.appId, cookie: options.cookie };
+    const response = await fetch(new URL('/v1/database/session', origin), { method: 'POST', headers: { 'content-type': 'application/json', authorization: 'Bearer ' + options.issuerCredential }, body: JSON.stringify(request), signal: options.signal, redirect: 'error' });
+    if (!response.ok)
+        throw new Error('Database session exchange denied or unavailable');
+    const result = await response.json();
+    if (typeof result !== "object" || result === null || !('token' in result) || typeof result.token !== "string" || !/^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(result.token))
+        throw new Error('Invalid database session response');
+    return result.token;
+}
+export { createStorageClient } from "./storage.js";
+export { createJobsClient } from "./tasks.js";
+export { serviceSessionsFromHeader } from "./services.js";
+export { AstrogateError } from "./http.js";

package/dist/services.d.ts

@@ -0,0 +1,7 @@
+import type { components } from "./wire.gen.js";
+export type ServiceBinding = components["schemas"]["ServiceBinding"];
+export type ServiceBindings = components["schemas"]["ServiceBindings"];
+export declare function serviceBindings(value: unknown): value is ServiceBindings;
+export type ServiceSessions = components["schemas"]["ServiceSessions"];
+export declare function serviceSessionsFromHeader(header: string | null): ServiceSessions;
+export declare function serviceURL(binding: ServiceBinding, path: string): URL;

package/dist/services.js

@@ -0,0 +1,53 @@
+import { AstrogateError, identifier, object } from "./http.js";
+export function serviceBindings(value) {
+    if (!object(value) || Object.keys(value).some(key => !["identity", "storage", "jobs"].includes(key)))
+        return false;
+    for (const key of ["identity", "storage", "jobs"]) {
+        const binding = value[key];
+        if (binding === undefined)
+            continue;
+        if (!object(binding) || typeof binding.resourceId !== "string" || typeof binding.endpoint !== "string" || typeof binding.authorityId !== "string" || typeof binding.cellId !== "string" || typeof binding.locationId !== "string" || typeof binding.environmentId !== "string" || (binding.environmentKind !== "preview" && binding.environmentKind !== "staging" && binding.environmentKind !== "production"))
+            return false;
+        try {
+            serviceURL({ resourceId: binding.resourceId, endpoint: binding.endpoint, authorityId: binding.authorityId, cellId: binding.cellId, locationId: binding.locationId, environmentId: binding.environmentId, environmentKind: binding.environmentKind }, "/");
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+// Use only the header overwritten by the trusted application gateway. A
+// standalone custom server must establish its own trusted ingress boundary.
+export function serviceSessionsFromHeader(header) {
+    if (header === null)
+        return {};
+    let value;
+    try {
+        value = JSON.parse(header);
+    }
+    catch {
+        throw new AstrogateError("invalid_service_sessions", 0, "", false);
+    }
+    if (!object(value) || Object.keys(value).some(key => key !== "storage" && key !== "jobs"))
+        throw new AstrogateError("invalid_service_sessions", 0, "", false);
+    const result = {};
+    for (const key of ["storage", "jobs"]) {
+        const session = value[key];
+        if (session === undefined)
+            continue;
+        if (!object(session) || Object.keys(session).sort().join(",") !== "resourceId,token" || typeof session.resourceId !== "string" || typeof session.token !== "string" || !/^[a-f0-9]{64}$/.test(session.token))
+            throw new AstrogateError("invalid_service_sessions", 0, "", false);
+        identifier(session.resourceId);
+        result[key] = { resourceId: session.resourceId, token: session.token };
+    }
+    return result;
+}
+export function serviceURL(binding, path) {
+    const url = new URL(binding.endpoint);
+    const localPreview = binding.environmentKind === "preview" && url.protocol === "http:" && ["127.0.0.1", "[::1]", "localhost"].includes(url.hostname);
+    if ((url.protocol !== "https:" && !localPreview) || url.username || url.password || url.pathname !== "/" || url.search || url.hash || !binding.authorityId || !binding.cellId || !binding.locationId || !binding.environmentId || !["preview", "staging", "production"].includes(binding.environmentKind))
+        throw new AstrogateError("invalid_service_binding", 0, "", false);
+    identifier(binding.resourceId);
+    return new URL(path, url);
+}

package/dist/storage.d.ts

@@ -0,0 +1,68 @@
+import type { components } from "./wire.gen.js";
+import type { ServiceBinding } from "./services.js";
+import { type MutationOptions, type TransportBudget } from "./http.js";
+export type StorageObject = components["schemas"]["StorageObject"];
+export type CreateStorageUpload = components["schemas"]["CreateStorageUpload"];
+export interface StorageOptions extends TransportBudget {
+    binding: ServiceBinding;
+    sessionToken?: string;
+}
+export declare function createStorageClient(options: StorageOptions): {
+    reserve: (input: CreateStorageUpload, controls: MutationOptions) => Promise<{
+        id: string;
+        resourceId: string;
+        sizeBytes: number;
+        sha256: string;
+        contentType: string;
+        filename: string;
+        state: "pending" | "ready" | "deleting" | "deleted";
+        retainUntil: string;
+    }>;
+    upload: (input: {
+        objectId: string;
+        body: Blob;
+    }, controls: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        id: string;
+        resourceId: string;
+        sizeBytes: number;
+        sha256: string;
+        contentType: string;
+        filename: string;
+        state: "pending" | "ready" | "deleting" | "deleted";
+        retainUntil: string;
+    }>;
+    metadata: (objectId: string, controls: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        id: string;
+        resourceId: string;
+        sizeBytes: number;
+        sha256: string;
+        contentType: string;
+        filename: string;
+        state: "pending" | "ready" | "deleting" | "deleted";
+        retainUntil: string;
+    }>;
+    download: (objectId: string, controls: {
+        signal?: AbortSignal;
+    }) => Promise<Response>;
+    delete: (objectId: string, controls: {
+        signal?: AbortSignal;
+    }) => Promise<undefined>;
+    references: {
+        attach: (input: {
+            objectId: string;
+            referenceId: string;
+        }, controls: {
+            signal?: AbortSignal;
+        }) => Promise<undefined>;
+        detach: (input: {
+            objectId: string;
+            referenceId: string;
+        }, controls: {
+            signal?: AbortSignal;
+        }) => Promise<undefined>;
+    };
+};

package/dist/storage.js

@@ -0,0 +1,30 @@
+import { serviceURL } from "./services.js";
+import { AstrogateError, identifier, object, requestJSON, requestResponse, validateBudget } from "./http.js";
+function storageObject(value) {
+    return object(value) && ["id", "resourceId", "sha256", "contentType", "filename", "retainUntil"].every(key => typeof value[key] === "string") && Number.isSafeInteger(value.sizeBytes) && Number(value.sizeBytes) >= 0 && ["pending", "ready", "deleting", "deleted"].includes(String(value.state));
+}
+export function createStorageClient(options) {
+    validateBudget(options);
+    serviceURL(options.binding, "/");
+    if (options.sessionToken && typeof window !== "undefined")
+        throw new AstrogateError("scoped_server_session_required", 0, "", false);
+    const base = `/v1/storage/${identifier(options.binding.resourceId)}`;
+    const headers = () => options.sessionToken ? { authorization: "Bearer " + options.sessionToken } : {};
+    const jsonHeaders = () => ({ ...headers(), "content-type": "application/json" });
+    const url = (path) => serviceURL(options.binding, base + path);
+    return {
+        reserve: (input, controls) => {
+            if (!controls.idempotencyKey)
+                throw new AstrogateError("idempotency_key_required", 0, "", false);
+            return requestJSON(url("/uploads"), options, { method: "POST", headers: { ...jsonHeaders(), "idempotency-key": controls.idempotencyKey }, credentials: "include", body: JSON.stringify(input) }, storageObject, controls.signal);
+        },
+        upload: (input, controls) => requestJSON(url(`/objects/${identifier(input.objectId)}`), options, { method: "PUT", headers: headers(), credentials: "include", body: input.body }, storageObject, controls.signal),
+        metadata: (objectId, controls) => requestJSON(url(`/objects/${identifier(objectId)}/metadata`), options, { headers: headers(), credentials: "include" }, storageObject, controls.signal),
+        download: (objectId, controls) => requestResponse(url(`/objects/${identifier(objectId)}`), options, { headers: headers(), credentials: "include" }, controls.signal),
+        delete: (objectId, controls) => requestJSON(url(`/objects/${identifier(objectId)}`), options, { method: "DELETE", headers: headers(), credentials: "include" }, (value) => value === undefined, controls.signal),
+        references: {
+            attach: (input, controls) => requestJSON(url(`/objects/${identifier(input.objectId)}/references`), options, { method: "POST", headers: jsonHeaders(), credentials: "include", body: JSON.stringify({ referenceId: input.referenceId }) }, (value) => value === undefined, controls.signal),
+            detach: (input, controls) => requestJSON(url(`/objects/${identifier(input.objectId)}/references`), options, { method: "DELETE", headers: jsonHeaders(), credentials: "include", body: JSON.stringify({ referenceId: input.referenceId }) }, (value) => value === undefined, controls.signal),
+        },
+    };
+}

package/dist/tasks.d.ts

@@ -0,0 +1,42 @@
+import type { components } from "./wire.gen.js";
+import { type ServiceBinding, type ServiceSessions } from "./services.js";
+import { type MutationOptions, type TransportBudget } from "./http.js";
+export interface TaskContext<Payload> {
+    payload: Payload;
+    runId: string;
+    idempotencyKey: string;
+    services: ServiceSessions;
+}
+export interface TaskDefinition<Payload extends Record<string, unknown>> {
+    parse(input: unknown): Payload;
+    run(context: TaskContext<Payload>): Promise<void>;
+}
+export type JobRunState = components["schemas"]["JobRunState"];
+type Parsers = Record<string, {
+    parse(input: unknown): Record<string, unknown>;
+}>;
+export declare function createJobsClient<Tasks extends Parsers>(options: TransportBudget & {
+    binding: ServiceBinding;
+    sessionToken: string;
+    tasks: Tasks;
+}): {
+    run: <Name extends Extract<keyof Tasks, string>>(input: {
+        task: Name;
+        payload: ReturnType<Tasks[Name]["parse"]>;
+    }, controls: MutationOptions) => Promise<{
+        operationId: string;
+        resourceId: string;
+        statusUrl: string;
+    }>;
+    get: (runId: string, controls: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        id: string;
+        operationId: string;
+        taskDefinitionRef: string;
+        state: "queued" | "running" | "waiting" | "succeeded" | "failed";
+        errorCode: string;
+        attempts: number;
+    }>;
+};
+export {};

package/dist/tasks.js

@@ -0,0 +1,24 @@
+import { serviceURL } from "./services.js";
+import { AstrogateError, identifier, object, requestJSON, validateBudget } from "./http.js";
+function accepted(value) { return object(value) && typeof value.operationId === "string" && typeof value.resourceId === "string" && typeof value.statusUrl === "string"; }
+function jobState(value) { return object(value) && typeof value.id === "string" && typeof value.operationId === "string" && typeof value.taskDefinitionRef === "string" && typeof value.errorCode === "string" && Number.isSafeInteger(value.attempts) && ["queued", "running", "waiting", "succeeded", "failed"].includes(String(value.state)); }
+// Tasks are server-only and always use the verified request user. The active
+// release alias is resolved and pinned once, inside metadata admission.
+export function createJobsClient(options) {
+    if (typeof window !== "undefined" || !options.sessionToken)
+        throw new AstrogateError("scoped_server_user_context_required", 0, "", false);
+    validateBudget(options);
+    const base = `/v1/jobs/${identifier(options.binding.resourceId)}`;
+    serviceURL(options.binding, "/");
+    return {
+        run: (input, controls) => {
+            const definition = options.tasks[input.task];
+            if (!definition || !controls.idempotencyKey)
+                throw new AstrogateError("registered_task_and_idempotency_required", 0, "", false);
+            const payload = definition.parse(input.payload);
+            const body = { taskDefinitionRef: `active:${identifier(input.task)}`, expectedEnvironmentKind: options.binding.environmentKind, payload };
+            return requestJSON(serviceURL(options.binding, `${base}/runs`), options, { method: "POST", headers: { authorization: "Bearer " + options.sessionToken, "content-type": "application/json", "idempotency-key": controls.idempotencyKey }, body: JSON.stringify(body) }, accepted, controls.signal);
+        },
+        get: (runId, controls) => requestJSON(serviceURL(options.binding, `${base}/runs/${identifier(runId)}`), options, { headers: { authorization: "Bearer " + options.sessionToken } }, jobState, controls.signal),
+    };
+}