@astrogate/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# Astrogate SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Scoped application and management clients for an existing, compatible Astrogate installation. Follow the [SDK guide](https://docs.astrogate.dev/docs/guides/sdk) for installation, execution contexts, credentials and supported capabilities. Documentation access is managed separately. Installing this package grants no infrastructure authority and does not install the platform or provision a cloud account.
+
+This package is publicly downloadable. First-party code is proprietary and is not released under an open-source license. Use requires authorization from the owner. The infrastructure repository remains private.
+
+Maintained native database clients and declarations are bundled with their upstream Apache-2.0 licenses, which remain applicable to those components. React remains an optional consumer peer. See THIRD_PARTY_NOTICES.md and native-provenance.json.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,17 @@
+# Bundled runtime dependencies
+
+The InstantDB clients retain their upstream package names, native runtime/type implementations and licenses. They are bundled components of this SDK, not packages published by Astrogate to the upstream npm namespace. Local modifications are recorded in native-provenance.json. Each bundled dependency retains its included license/notices.
+
+- @instantdb/admin@0.0.0: Apache-2.0
+- @instantdb/core@0.0.0: Apache-2.0
+- @instantdb/version@0.0.0: Apache-2.0
+- mutative@2.0.1: MIT
+- uuid@14.0.3: MIT
+- @instantdb/webhooks@0.0.0: Apache-2.0
+- cookie@2.0.1: MIT
+- @instantdb/eventsource@4.1.0-2: MIT
+- eventsource-parser@3.1.1: MIT
+- @instantdb/react@0.0.0: Apache-2.0
+- @instantdb/react-common@0.0.0: Apache-2.0
+- eventsource@5.1.3: MIT
+- eventsource-parser@4.1.3: MIT

package/dist/browser.d.ts

@@ -0,0 +1,85 @@
+import { init } from "@instantdb/core";
+import { type DatabaseBinding } from "./database-binding.js";
+export { i, id, lookup } from "@instantdb/core";
+export type * from "@instantdb/core";
+export { createAuthClient } from "better-auth/client";
+export type { DatabaseBinding } from "./database-binding.js";
+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/core").InstantCoreDatabase<Schema, Dates>;
+};
+export { getHostedDatabaseSession } from "./hosted-session.js";
+export { createStorageClient } from "./storage.js";
+export type { StorageObject, CreateStorageUpload, StorageOptions } from "./storage.js";
+export type { ServiceBinding, ServiceBindings } from "./services.js";
+export { AstrogateError } from "./http.js";
+import { type StorageOptions } from "./storage.js";
+export declare function createApplication<Auth>(options: {
+    auth: Auth;
+    storage?: StorageOptions;
+}): {
+    auth: Auth;
+    storage: {
+        reserve: (input: import("./storage.js").CreateStorageUpload, controls: import("./http.js").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>;
+        };
+    } | undefined;
+};

package/dist/browser.js

@@ -0,0 +1,16 @@
+import { init } from "@instantdb/core";
+import { databaseEndpoint } from "./database-binding.js";
+export { i, id, lookup } from "@instantdb/core";
+export { createAuthClient } from "better-auth/client";
+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 { createStorageClient } from "./storage.js";
+export { AstrogateError } from "./http.js";
+import { createStorageClient } from "./storage.js";
+// Compose the actual native auth client without narrowing its plugin methods.
+export function createApplication(options) {
+    return { auth: options.auth, storage: options.storage ? createStorageClient(options.storage) : undefined };
+}

package/dist/database-binding.d.ts

@@ -0,0 +1,7 @@
+import type { components } from "./wire.gen.js";
+export type DatabaseBinding = components["schemas"]["DatabaseBinding"];
+export declare function databaseEndpoint(binding: DatabaseBinding): {
+    appId: string;
+    apiURI: string;
+    websocketURI: string;
+};

package/dist/database-binding.js

@@ -0,0 +1,11 @@
+// Bindings come from authenticated environment resolution. Neither NODE_ENV,
+// a branch name nor SDK import chooses Production or installs infrastructure.
+export function databaseEndpoint(binding) {
+    const http = new URL(binding.apiURI), socket = new URL(binding.websocketURI);
+    if (binding.state !== "ready" || !Number.isSafeInteger(binding.revision) || binding.revision <= 0 || !binding.environmentId ||
+        !["preview", "staging", "production"].includes(binding.environmentKind) ||
+        !/^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(binding.appId) ||
+        http.protocol !== "https:" || socket.protocol !== "wss:" || http.username || http.password || socket.username || socket.password || http.search || http.hash || socket.search || socket.hash || http.origin !== socket.origin.replace(/^wss:/, "https:") || socket.pathname !== "/runtime/session" || !["", "/"].includes(http.pathname))
+        throw new Error("An authorized ready database binding with protected endpoints is required");
+    return { appId: binding.appId, apiURI: binding.apiURI, websocketURI: binding.websocketURI };
+}

package/dist/hosted-session.d.ts

@@ -0,0 +1 @@
+export declare function getHostedDatabaseSession(signal: AbortSignal): Promise<string>;

package/dist/hosted-session.js

@@ -0,0 +1,11 @@
+// Explicit hosted Preview access, using the same native session bridge as SSR.
+// Importing the SDK never selects an environment or starts dependencies.
+export async function getHostedDatabaseSession(signal) {
+    const response = await fetch('/__astrogate/database-session', { method: 'POST', credentials: 'same-origin', cache: 'no-store', redirect: 'error', signal });
+    if (!response.ok)
+        throw new Error('Hosted database session 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 hosted database session response');
+    return result.token;
+}

package/dist/http.d.ts

@@ -0,0 +1,24 @@
+export declare class AstrogateError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly requestId: string;
+    readonly retryable: boolean;
+    constructor(code: string, status: number, requestId: string, retryable: boolean);
+}
+export interface TransportBudget {
+    deadlineMs: number;
+    maxAttempts: number;
+}
+export interface MutationOptions {
+    idempotencyKey: string;
+    signal?: AbortSignal;
+}
+export declare function object(value: unknown): value is Record<string, unknown>;
+export declare function identifier(value: string): string;
+export declare function validateBudget(options: TransportBudget): void;
+export declare function requestResponse(url: URL, options: TransportBudget, input: RequestInit, signal?: AbortSignal): Promise<Response>;
+export declare function requestJSON<T>(url: URL, budget: TransportBudget, input: RequestInit, validate: (value: unknown) => value is T, signal?: AbortSignal): Promise<T>;
+export declare function managementAuthority(options: TransportBudget & {
+    endpoint: string;
+    token: string;
+}): URL;

package/dist/http.js

@@ -0,0 +1,92 @@
+// Shared owned HTTP behavior. Native database/auth clients retain their own
+// return values and transport semantics.
+export class AstrogateError extends Error {
+    code;
+    status;
+    requestId;
+    retryable;
+    constructor(code, status, requestId, retryable) {
+        super(code);
+        this.code = code;
+        this.status = status;
+        this.requestId = requestId;
+        this.retryable = retryable;
+        this.name = "AstrogateError";
+    }
+}
+export function object(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
+export function identifier(value) { if (!/^[A-Za-z0-9_-]+$/.test(value))
+    throw new AstrogateError("invalid_resource_reference", 0, "", false); return value; }
+export function validateBudget(options) { if (!Number.isSafeInteger(options.deadlineMs) || options.deadlineMs <= 0 || !Number.isSafeInteger(options.maxAttempts) || options.maxAttempts < 1)
+    throw new AstrogateError("explicit_transport_budget_required", 0, "", false); }
+function delay(ms, signal) { return new Promise((resolve, reject) => { if (signal.aborted) {
+    reject(signal.reason);
+    return;
+} const abort = () => { clearTimeout(timer); reject(signal.reason); }; const timer = setTimeout(() => { signal.removeEventListener("abort", abort); resolve(); }, ms); signal.addEventListener("abort", abort, { once: true }); }); }
+export async function requestResponse(url, options, input, signal) {
+    validateBudget(options);
+    const combined = signal ? AbortSignal.any([AbortSignal.timeout(options.deadlineMs), signal]) : AbortSignal.timeout(options.deadlineMs);
+    let last;
+    for (let attempt = 0; attempt < options.maxAttempts; attempt++) {
+        let retryAfter = 0;
+        try {
+            const response = await fetch(url, { ...input, signal: combined, redirect: "error", cache: "no-store" });
+            if (response.ok)
+                return response;
+            const after = response.headers.get("retry-after");
+            if (after) {
+                const seconds = Number(after);
+                retryAfter = Number.isFinite(seconds) ? Math.max(0, seconds * 1000) : Math.max(0, Date.parse(after) - Date.now());
+            }
+            let value;
+            try {
+                value = await response.json();
+            }
+            catch {
+                throw new AstrogateError("invalid_error_response", response.status, "", false);
+            }
+            if (!object(value) || typeof value.code !== "string" || typeof value.requestId !== "string" || typeof value.retryable !== "boolean")
+                throw new AstrogateError("invalid_error_response", response.status, "", false);
+            throw new AstrogateError(value.code, response.status, value.requestId, value.retryable);
+        }
+        catch (error) {
+            if (combined.aborted)
+                throw combined.reason;
+            last = error;
+            if (error instanceof AstrogateError && !error.retryable)
+                throw error;
+            if (attempt + 1 === options.maxAttempts)
+                break;
+            await delay(Math.max(retryAfter, 100 * 2 ** attempt * (0.5 + Math.random())), combined);
+        }
+    }
+    if (last instanceof AstrogateError)
+        throw last;
+    throw new AstrogateError("transport_unavailable", 0, "", true);
+}
+export async function requestJSON(url, budget, input, validate, signal) {
+    const response = await requestResponse(url, budget, input, signal);
+    let value;
+    try {
+        value = response.status === 204 ? undefined : await response.json();
+    }
+    catch {
+        throw new AstrogateError("invalid_response", response.status, response.headers.get("x-request-id") ?? "", false);
+    }
+    if (!validate(value))
+        throw new AstrogateError("invalid_response", response.status, response.headers.get("x-request-id") ?? "", false);
+    return value;
+}
+// Management and platform inventory share one authority/transport boundary.
+// Neither credential is accepted in a browser or followed across a redirect.
+export function managementAuthority(options) {
+    if (typeof window !== "undefined")
+        throw new AstrogateError("server_only_entrypoint", 0, "", false);
+    const endpoint = new URL(options.endpoint);
+    if ((endpoint.protocol !== "https:" && !(endpoint.protocol === "http:" && ["127.0.0.1", "[::1]", "localhost"].includes(endpoint.hostname))) || endpoint.username || endpoint.password || endpoint.search || endpoint.hash || endpoint.pathname !== "/")
+        throw new AstrogateError("unsafe_management_authority", 0, "", false);
+    validateBudget(options);
+    if (!options.token)
+        throw new AstrogateError("credential_required", 0, "", false);
+    return endpoint;
+}

package/dist/inventory.d.ts

@@ -0,0 +1,7 @@
+import type { components, operations } from "./wire.gen.js";
+export type PageOptions = NonNullable<operations["listProjects"]["parameters"]["query"]>;
+export type InventoryPage<T> = Omit<components["schemas"]["ProjectPage"], "items"> & {
+    items: T[];
+};
+export declare function listQuery(options: PageOptions): string;
+export declare function pageOf<T>(item: (value: unknown) => value is T): (value: unknown) => value is InventoryPage<T>;

package/dist/inventory.js

@@ -0,0 +1,18 @@
+import { AstrogateError, object } from "./http.js";
+export function listQuery(options) {
+    const query = new URLSearchParams();
+    if (options.limit !== undefined) {
+        if (!Number.isSafeInteger(options.limit) || options.limit < 1)
+            throw new AstrogateError("invalid_page_limit", 0, "", false);
+        query.set("limit", String(options.limit));
+    }
+    if (options.cursor !== undefined)
+        query.set("cursor", options.cursor);
+    return query.size ? `?${query}` : "";
+}
+export function pageOf(item) {
+    return (value) => object(value) &&
+        typeof value.nextCursor === "string" &&
+        Array.isArray(value.items) &&
+        value.items.every(item);
+}

package/dist/management-read.d.ts

@@ -0,0 +1,17 @@
+import type { components } from "./wire.gen.js";
+type Schemas = components["schemas"];
+type Project = Schemas["Project"];
+type PlacementState = Schemas["PlacementState"];
+type PlacementLocation = Schemas["PlacementLocation"];
+export declare function hostnameBinding(value: unknown): value is Schemas["HostnameBinding"];
+export declare function operationLog(value: unknown): value is Schemas["OperationLog"];
+export declare function operatorOperationDetail(value: unknown): value is Schemas["OperatorOperationDetail"];
+export declare function project(value: unknown): value is Project;
+export declare function environment(value: unknown): value is Schemas["Environment"];
+export declare function placementState(value: unknown): value is PlacementState;
+export declare function placementLocations(value: unknown): value is PlacementLocation[];
+type Operation = Schemas["Operation"];
+type BuildingBlock = Schemas["BuildingBlock"];
+export declare function operation(value: unknown): value is Operation;
+export declare function buildingBlock(value: unknown): value is BuildingBlock;
+export {};

package/dist/management-read.js

@@ -0,0 +1,104 @@
+import { object } from "./http.js";
+export function hostnameBinding(value) {
+    return object(value) && ["id", "hostname", "reason"].every(key => typeof value[key] === "string") &&
+        typeof value.primary === "boolean" && Number.isSafeInteger(value.revision) &&
+        typeof value.state === "string" && ["pending", "ready", "failed", "retiring", "retired"].includes(value.state);
+}
+export function operationLog(value) {
+    return object(value) && typeof value.operationId === "string" &&
+        (value.kind === "build" || value.kind === "execution") &&
+        typeof value.available === "boolean" && typeof value.text === "string";
+}
+export function operatorOperationDetail(value) {
+    return object(value) && operation(value.operation) && Array.isArray(value.logKinds) &&
+        value.logKinds.every(kind => kind === "build" || kind === "execution");
+}
+export function project(value) {
+    return (object(value) &&
+        typeof value.id === "string" &&
+        typeof value.name === "string" &&
+        Number.isSafeInteger(value.revision));
+}
+export function environment(value) {
+    return (object(value) &&
+        typeof value.id === "string" &&
+        typeof value.projectId === "string" &&
+        typeof value.name === "string" &&
+        (value.kind === "preview" ||
+            value.kind === "staging" ||
+            value.kind === "production") &&
+        Number.isSafeInteger(value.revision));
+}
+export function placementState(value) {
+    if (!object(value) || !object(value.desired) || !object(value.reserved))
+        return false;
+    if (value.recoveryPoint !== undefined &&
+        (!object(value.recoveryPoint) ||
+            typeof value.recoveryPoint.cell !== "string" ||
+            typeof value.recoveryPoint.capturedAt !== "string" ||
+            !Number.isFinite(Date.parse(value.recoveryPoint.capturedAt))))
+        return false;
+    if (value.capacity !== undefined) {
+        const capacity = value.capacity;
+        if (!object(capacity) || !resources(capacity.maximum) ||
+            !Array.isArray(capacity.required) || !capacity.required.every((kind) => typeof kind === "string") ||
+            typeof capacity.evidence !== "string" || !Number.isSafeInteger(capacity.cellCostMicrosPerHour) || Number(capacity.cellCostMicrosPerHour) < 0)
+            return false;
+        if (capacity.highWater !== undefined) {
+            const usage = capacity.highWater;
+            if (!object(usage) || !resources(usage.resources) || typeof usage.fresh !== "boolean" ||
+                typeof usage.validUntil !== "string" || !Number.isFinite(Date.parse(usage.validUntil)))
+                return false;
+        }
+    }
+    return (Number.isSafeInteger(value.revision) &&
+        Number.isSafeInteger(value.epoch) &&
+        [
+            "effectiveCell",
+            "effectiveLocation",
+            "effectiveProfile",
+            "operationId",
+            "reason",
+            "standbyCell",
+        ].every((key) => typeof value[key] === "string") &&
+        [
+            "pending",
+            "ready",
+            "draining",
+            "fenced",
+            "copying",
+            "verified",
+            "committed",
+            "routing",
+            "waiting",
+        ].includes(String(value.phase)) &&
+        ["none", "pending", "snapshot-ready", "degraded"].includes(String(value.protection)) &&
+        ["onDemand", "alwaysOn"].includes(String(value.desired.runtimeMode)) &&
+        ["capacityProfile", "location", "standbyLocation"].every((key) => object(value.desired) && typeof value.desired[key] === "string") &&
+        resources(value.reserved));
+}
+function resources(value) {
+    return object(value) && ["millicpu", "memoryBytes", "storageBytes"].every(key => Number.isSafeInteger(value[key]) && Number(value[key]) >= 0);
+}
+export function placementLocations(value) {
+    return (Array.isArray(value) &&
+        value.every((location) => object(location) &&
+            ["id", "name", "geographicGroup"].every((key) => typeof location[key] === "string") &&
+            typeof location.healthy === "boolean" &&
+            Array.isArray(location.profiles) &&
+            location.profiles.every((profile) => typeof profile === "string")));
+}
+export function operation(value) {
+    return (object(value) &&
+        typeof value.id === "string" &&
+        typeof value.resourceId === "string" &&
+        typeof value.state === "string" &&
+        ["queued", "running", "waiting", "succeeded", "failed"].includes(value.state) &&
+        typeof value.step === "string" &&
+        ["accepted", "provisioning", "verifying", "complete"].includes(value.step) &&
+        Number.isSafeInteger(value.attempts) &&
+        typeof value.errorCode === "string");
+}
+export function buildingBlock(value) {
+    return object(value) && typeof value.id === "string" && typeof value.profileId === "string" && typeof value.kind === "string" && ["identity", "storage", "jobs", "schedule"].includes(value.kind) && typeof value.state === "string" && ["pending", "ready", "retained", "failed"].includes(value.state) && Number.isSafeInteger(value.revision) && object(value.binding) && typeof value.binding.resourceId === "string" && typeof value.binding.endpoint === "string" && typeof value.binding.authorityId === "string";
+}