@nofra/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @nofra/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.
+The JavaScript and TypeScript client for [nøfra](https://nofra.net/).
+
+```sh
+npm install @nofra/sdk
+```
+
+```ts
+import { createClient } from "@nofra/sdk";
+
+const nofra = createClient({
+  app: "my-app",
+  subdomain: "my-app-account-example",
+});
+```
+
+The subdomain is needed for authentication on localhost or outside a browser;
+in a browser the SDK normally uses the current hostname.
+
+For database and storage access, call a server-side Function from the browser
+and create a separate SDK client in the Function using the automatically
+injected `APP_SERVER_TOKEN`. Never expose this token in browser code. Validate
+the caller and enforce access to private data in your Function.
+
+See the [SDK guide](https://nofra.net/docs/sdk) and
+[Functions guide](https://nofra.net/docs/functions) for examples.

package/dist/index.d.ts

@@ -0,0 +1,296 @@
+/**
+ * @nofra/sdk — Official JavaScript & TypeScript SDK for Nofra
+ * "No infrastructure. Just apps."
+ */
+export interface NofraClientOptions {
+    /** Name of the Nofra application (e.g. "todo-app") */
+    app: string;
+    /**
+     * App subdomain (`<app>-<account>-<hash>`) or full hostname, used for
+     * auth. Defaults to the current hostname in browsers; required on
+     * localhost and outside browsers.
+     */
+    subdomain?: string;
+    /** Control plane API URL (defaults to "https://api.nofra.net") */
+    apiUrl?: string;
+    /** Optional API token for authenticated requests */
+    apiKey?: string;
+}
+export type AppStatus = "running" | "deploying" | "stopped";
+export interface ServiceStatus {
+    name: "Compute" | "Database" | "Storage" | "Auth" | "Functions" | "Domains";
+    enabled: boolean;
+}
+export interface UsageMetric {
+    label: "Requests" | "Database" | "Storage" | "Bandwidth";
+    used: number;
+    limit: number;
+    unit: "req" | "GB";
+}
+export interface AppInfo {
+    id: string;
+    name: string;
+    url: string;
+    status: AppStatus;
+    last_deploy: string;
+    services: ServiceStatus[];
+    usage: UsageMetric[];
+}
+/** Creates an app with managed services available on demand. */
+export interface CreateAppOptions {
+    name: string;
+}
+/** Only the display URL is editable through this SDK method. */
+export interface UpdateAppOptions {
+    url?: string;
+}
+export interface LogEntry {
+    id: string;
+    app_name: string | null;
+    deployment_id: string | null;
+    level: "info" | "success" | "warn" | "error";
+    scope: "deploy" | "account" | "runtime";
+    message: string;
+    timestamp: string;
+}
+export interface UserInfo {
+    account: string;
+    username: string;
+    plan: string;
+    limits: {
+        requests: number;
+        database_gb: number;
+        storage_gb: number;
+        bandwidth_gb: number;
+    };
+}
+export interface DatabaseStatus {
+    app: string;
+    enabled: boolean;
+    used_gb: number;
+    limit_gb: number;
+}
+export interface CollectionRecord<T = Record<string, unknown>> {
+    id: string;
+    collection: string;
+    data: T;
+    created_at: string;
+}
+export interface CollectionFilter {
+    /** A top-level field in record data, not an SQL expression or nested path. */
+    field: string;
+    op: "eq" | "ne" | "gt" | "gte" | "lt" | "lte";
+    value: string | number | boolean | null;
+}
+export interface CollectionListOptions {
+    limit?: number;
+    cursor?: string;
+    filters?: CollectionFilter[];
+    sort?: "created_at" | "id" | `data.${string}`;
+    order?: "asc" | "desc";
+}
+export interface CollectionPage<T = Record<string, unknown>> {
+    records: CollectionRecord<T>[];
+    next_cursor: string | null;
+}
+export interface StorageObjectInfo {
+    key: string;
+    size: number;
+    uploaded: string;
+    /** Stored content type; absent for objects written before file support. */
+    contentType?: string;
+}
+export interface DatabaseRecovery {
+    id: string;
+    status: "queued" | "ready" | "failed";
+    timestamp: string | null;
+    created_at: string;
+    expires_at: string;
+    previous_available: boolean;
+    error_message: string | null;
+}
+export interface DatabaseRecoveryStatus {
+    platform_enabled: boolean;
+    recovery_days: number;
+    enabled: boolean;
+    active_recovery_id: string | null;
+    recoveries: DatabaseRecovery[];
+}
+export interface DeletedStorageObject {
+    id: string;
+    key: string;
+    size: number;
+    contentType?: string;
+    deleted_at: string;
+    expires_at: string;
+}
+export interface StorageTrashPage {
+    objects: DeletedStorageObject[];
+    cursor: string | null;
+    recovery_days: number;
+}
+/** Binary payload accepted by `storage.putFile`. */
+export type StorageFileData = Blob | ArrayBuffer | Uint8Array;
+export interface AppAuthUser {
+    id: string;
+    name: string;
+    email: string;
+    emailVerified: boolean;
+    createdAt: string;
+    disabled?: boolean;
+    deletion_pending?: boolean;
+}
+export interface AppAuthUsersPage {
+    enabled: boolean;
+    users: AppAuthUser[];
+    next_offset: number | null;
+    deletion_webhook: boolean;
+}
+export interface AppAuthSession {
+    id: string;
+    token: string;
+    userId: string;
+    expiresAt: string;
+}
+export declare class NofraError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare class NofraClient {
+    readonly appName: string;
+    readonly apiUrl: string;
+    private readonly apiKey?;
+    private readonly subdomain?;
+    readonly app: {
+        getInfo: () => Promise<AppInfo>;
+        getLogs: () => Promise<LogEntry[]>;
+        deploy: () => Promise<{
+            id: string;
+            app: string;
+            status: string;
+            url: string;
+        }>;
+    };
+    readonly apps: {
+        create: (options: CreateAppOptions) => Promise<AppInfo>;
+        update: (name: string, options: UpdateAppOptions) => Promise<AppInfo>;
+    };
+    readonly db: {
+        /** Pro/Team owners and admins only. Use an administrative token server-side. */
+        recovery: () => Promise<DatabaseRecoveryStatus>;
+        restore: (timestamp: string, confirm: string) => Promise<{
+            id: string;
+            status: "queued";
+        }>;
+        restorePrevious: (id: string, confirm: string) => Promise<{
+            id: string;
+            status: "queued";
+        }>;
+        status: () => Promise<DatabaseStatus>;
+        list: <T = Record<string, unknown>>(collection: string) => Promise<CollectionRecord<T>[]>;
+        listPage: <T = Record<string, unknown>>(collection: string, options?: CollectionListOptions) => Promise<CollectionPage<T>>;
+        get: <T = Record<string, unknown>>(collection: string, id: string) => Promise<CollectionRecord<T>>;
+        /** Replace the entire data value; keeps the record ID and created_at. */
+        update: <T = Record<string, unknown>>(collection: string, id: string, data: T) => Promise<CollectionRecord<T>>;
+        /** Atomically merge top-level fields. Nested values are replaced; null is stored. */
+        patch: <T = Record<string, unknown>>(collection: string, id: string, data: Partial<T>) => Promise<CollectionRecord<T>>;
+        insert: <T = Record<string, unknown>>(collection: string, data: T) => Promise<CollectionRecord<T>>;
+        delete: (collection: string, id: string) => Promise<{
+            deleted: boolean;
+            id: string;
+        }>;
+    };
+    readonly storage: {
+        /** Pro/Team owners and admins only. Pass the returned cursor to read more. */
+        trash: (cursor?: string) => Promise<StorageTrashPage>;
+        restore: (id: string) => Promise<{
+            restored: boolean;
+            key: string;
+        }>;
+        list: () => Promise<StorageObjectInfo[]>;
+        listPage: (cursor?: string) => Promise<{
+            objects: StorageObjectInfo[];
+            cursor: string | null;
+        }>;
+        putText: (key: string, content: string) => Promise<{
+            key: string;
+            size: number;
+        }>;
+        getText: (key: string) => Promise<string>;
+        putFile: (key: string, data: StorageFileData, contentType?: string) => Promise<{
+            key: string;
+            size: number;
+            contentType: string;
+        }>;
+        getFile: (key: string) => Promise<Blob>;
+        delete: (key: string) => Promise<{
+            deleted: boolean;
+            key: string;
+            recovery?: {
+                id: string;
+                expires_at: string;
+            };
+        }>;
+    };
+    readonly auth: {
+        me: () => Promise<UserInfo>;
+        signUp: (params: {
+            email: string;
+            password: string;
+            name?: string;
+        }) => Promise<{
+            token: string | null;
+            user: AppAuthUser;
+        }>;
+        signIn: (params: {
+            email: string;
+            password: string;
+        }) => Promise<{
+            token: string | null;
+            user: AppAuthUser;
+        }>;
+        signOut: (token?: string) => Promise<{
+            signed_out: boolean;
+        }>;
+        getSession: (token?: string) => Promise<{
+            session: AppAuthSession | null;
+            user: AppAuthUser | null;
+        }>;
+        listUsers: (query?: string) => Promise<AppAuthUser[]>;
+        listUsersPage: (query?: string, offset?: number) => Promise<AppAuthUsersPage>;
+        setUserDisabled: (id: string, disabled: boolean) => Promise<{
+            disabled: boolean;
+        }>;
+        deleteUser: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+        /** Login types currently usable on the app (email + credentialed socials). */
+        getLoginTypes: () => Promise<{
+            email: boolean;
+            social: string[];
+        }>;
+        /** Plain-link URL that starts a social login for `provider`. */
+        getSocialSignInUrl: (provider: string, callbackURL: string) => string;
+        /** Redirects the browser to start a social login (defaults to this page). */
+        signInWithSocial: (provider: string, callbackURL?: string) => void;
+        /**
+         * Reads the social-login result (`token` or `error`) from the current URL
+         * and strips it from the address bar. Returns nulls outside the browser.
+         */
+        consumeSocialResult: () => {
+            token: string | null;
+            error: string | null;
+        };
+    };
+    constructor(options: NofraClientOptions);
+    /**
+     * Identifier for the public auth endpoints: the explicit `subdomain`
+     * option, or the current hostname in browsers (the server matches it
+     * against subdomains and custom domains). App names are only unique per
+     * account, so they cannot identify an app on account-less routes.
+     */
+    private authAppId;
+    private request;
+    private requestRaw;
+}
+export declare function createClient(options: NofraClientOptions): NofraClient;

package/dist/index.js

@@ -0,0 +1,309 @@
+/**
+ * @nofra/sdk — Official JavaScript & TypeScript SDK for Nofra
+ * "No infrastructure. Just apps."
+ */
+export class NofraError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "NofraError";
+        this.status = status;
+    }
+}
+export class NofraClient {
+    appName;
+    apiUrl;
+    apiKey;
+    subdomain;
+    app;
+    apps;
+    db;
+    storage;
+    auth;
+    constructor(options) {
+        if (!options.app) {
+            throw new Error("NofraClient requires an 'app' name.");
+        }
+        this.appName = options.app;
+        this.apiUrl = (options.apiUrl ?? "https://api.nofra.net").replace(/\/+$/, "");
+        this.apiKey = options.apiKey;
+        this.subdomain = options.subdomain;
+        const encodedApp = encodeURIComponent(this.appName);
+        this.apps = {
+            create: async (options) => {
+                const res = await this.request("/v1/apps", {
+                    method: "POST",
+                    body: JSON.stringify(options),
+                });
+                return res.app;
+            },
+            update: async (name, options) => {
+                const res = await this.request(`/v1/apps/${encodeURIComponent(name)}`, {
+                    method: "PATCH",
+                    body: JSON.stringify(options),
+                });
+                return res.app;
+            },
+        };
+        this.app = {
+            getInfo: async () => {
+                const res = await this.request(`/v1/apps/${encodedApp}`);
+                return res.app;
+            },
+            getLogs: async () => {
+                const res = await this.request(`/v1/apps/${encodedApp}/logs`);
+                return res.logs;
+            },
+            deploy: async () => {
+                const res = await this.request(`/v1/apps/${encodedApp}/deployments`, {
+                    method: "POST",
+                    body: JSON.stringify({}),
+                });
+                return res.deployment;
+            },
+        };
+        this.db = {
+            recovery: () => this.request(`/v1/apps/${encodedApp}/db/recovery`),
+            restore: async (timestamp, confirm) => {
+                const response = await this.request(`/v1/apps/${encodedApp}/db/recovery`, { method: "POST", body: JSON.stringify({ timestamp, confirm }) });
+                return response.recovery;
+            },
+            restorePrevious: async (id, confirm) => {
+                const response = await this.request(`/v1/apps/${encodedApp}/db/recovery`, { method: "POST", body: JSON.stringify({ previous_id: id, confirm }) });
+                return response.recovery;
+            },
+            status: async () => {
+                const res = await this.request(`/v1/apps/${encodedApp}/db/status`);
+                return res.database;
+            },
+            list: async (collection) => {
+                const col = encodeURIComponent(collection);
+                const res = await this.request(`/v1/apps/${encodedApp}/db/collections/${col}`);
+                return res.records;
+            },
+            listPage: (collection, options = {}) => {
+                const params = new URLSearchParams({ limit: String(options.limit ?? 100) });
+                if (options.cursor !== undefined)
+                    params.set("cursor", options.cursor);
+                if (options.filters !== undefined)
+                    params.set("filters", JSON.stringify(options.filters));
+                if (options.sort !== undefined)
+                    params.set("sort", options.sort);
+                if (options.order !== undefined)
+                    params.set("order", options.order);
+                return this.request(`/v1/apps/${encodedApp}/db/collections/${encodeURIComponent(collection)}?${params}`);
+            },
+            get: async (collection, id) => {
+                const res = await this.request(`/v1/apps/${encodedApp}/db/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`);
+                return res.record;
+            },
+            update: async (collection, id, data) => {
+                const res = await this.request(`/v1/apps/${encodedApp}/db/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`, { method: "PUT", body: JSON.stringify({ data }) });
+                return res.record;
+            },
+            patch: async (collection, id, data) => {
+                const res = await this.request(`/v1/apps/${encodedApp}/db/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`, { method: "PATCH", body: JSON.stringify({ data }) });
+                return res.record;
+            },
+            insert: async (collection, data) => {
+                const col = encodeURIComponent(collection);
+                const res = await this.request(`/v1/apps/${encodedApp}/db/collections/${col}`, {
+                    method: "POST",
+                    body: JSON.stringify({ data }),
+                });
+                return res.record;
+            },
+            delete: async (collection, id) => {
+                const col = encodeURIComponent(collection);
+                const recId = encodeURIComponent(id);
+                return this.request(`/v1/apps/${encodedApp}/db/collections/${col}/${recId}`, { method: "DELETE" });
+            },
+        };
+        this.storage = {
+            listPage: (cursor) => this.request(`/v1/apps/${encodedApp}/storage${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ""}`),
+            trash: (cursor) => this.request(`/v1/apps/${encodedApp}/storage-trash${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ""}`),
+            restore: (id) => this.request(`/v1/apps/${encodedApp}/storage-trash/${encodeURIComponent(id)}/restore`, { method: "POST", body: JSON.stringify({}) }),
+            list: async () => {
+                const res = await this.request(`/v1/apps/${encodedApp}/storage`);
+                return res.objects;
+            },
+            putFile: async (key, data, contentType) => {
+                const encodedKey = encodeURIComponent(key);
+                const blobType = data instanceof Blob ? data.type : "";
+                const resolvedType = contentType || blobType || "application/octet-stream";
+                // Copy views into a plain buffer: fetch types only accept ArrayBuffer-backed bodies.
+                const body = data instanceof Uint8Array ? data.slice().buffer : data;
+                return this.request(`/v1/apps/${encodedApp}/storage/${encodedKey}?raw=1`, {
+                    method: "PUT",
+                    headers: { "Content-Type": resolvedType },
+                    body,
+                });
+            },
+            getFile: async (key) => {
+                const encodedKey = encodeURIComponent(key);
+                const res = await this.requestRaw(`/v1/apps/${encodedApp}/storage/${encodedKey}?raw=1`);
+                return res.blob();
+            },
+            putText: async (key, content) => {
+                const encodedKey = encodeURIComponent(key);
+                return this.request(`/v1/apps/${encodedApp}/storage/${encodedKey}`, {
+                    method: "PUT",
+                    body: JSON.stringify({ content }),
+                });
+            },
+            getText: async (key) => {
+                const encodedKey = encodeURIComponent(key);
+                const res = await this.request(`/v1/apps/${encodedApp}/storage/${encodedKey}`);
+                return res.content;
+            },
+            delete: async (key) => {
+                const encodedKey = encodeURIComponent(key);
+                return this.request(`/v1/apps/${encodedApp}/storage/${encodedKey}`, { method: "DELETE" });
+            },
+        };
+        this.auth = {
+            me: async () => {
+                return this.request("/v1/me");
+            },
+            signUp: async (params) => {
+                const authApp = encodeURIComponent(this.authAppId());
+                return this.request(`/v1/apps/${authApp}/auth/sign-up`, {
+                    method: "POST",
+                    body: JSON.stringify(params),
+                });
+            },
+            signIn: async (params) => {
+                const authApp = encodeURIComponent(this.authAppId());
+                return this.request(`/v1/apps/${authApp}/auth/sign-in`, {
+                    method: "POST",
+                    body: JSON.stringify(params),
+                });
+            },
+            signOut: async (token) => {
+                const authApp = encodeURIComponent(this.authAppId());
+                return this.request(`/v1/apps/${authApp}/auth/sign-out`, {
+                    method: "POST",
+                    headers: token ? { "X-Nofra-App-Token": token } : undefined,
+                    body: JSON.stringify({}),
+                });
+            },
+            getSession: async (token) => {
+                const authApp = encodeURIComponent(this.authAppId());
+                return this.request(`/v1/apps/${authApp}/auth/session`, {
+                    headers: token ? { "X-Nofra-App-Token": token } : undefined,
+                });
+            },
+            listUsers: async (query = "") => {
+                const res = await this.request(`/v1/apps/${encodedApp}/auth/users?q=${encodeURIComponent(query)}&offset=0`);
+                return res.users;
+            },
+            listUsersPage: (query = "", offset = 0) => this.request(`/v1/apps/${encodedApp}/auth/users?q=${encodeURIComponent(query)}&offset=${offset}`),
+            setUserDisabled: (id, disabled) => this.request(`/v1/apps/${encodedApp}/auth/users/${encodeURIComponent(id)}`, { method: "PATCH", body: JSON.stringify({ disabled }) }),
+            deleteUser: (id) => this.request(`/v1/apps/${encodedApp}/auth/users/${encodeURIComponent(id)}`, { method: "DELETE", body: JSON.stringify({ confirm: id }) }),
+            getLoginTypes: async () => {
+                const authApp = encodeURIComponent(this.authAppId());
+                return this.request(`/v1/apps/${authApp}/auth/config`);
+            },
+            getSocialSignInUrl: (provider, callbackURL) => {
+                const authApp = encodeURIComponent(this.authAppId());
+                return (`${this.apiUrl}/v1/apps/${authApp}/auth/social-start` +
+                    `?provider=${encodeURIComponent(provider)}` +
+                    `&to=${encodeURIComponent(callbackURL)}`);
+            },
+            signInWithSocial: (provider, callbackURL) => {
+                if (typeof window === "undefined" || !window.location) {
+                    throw new Error("signInWithSocial needs a browser. Use getSocialSignInUrl() to build the link instead.");
+                }
+                const target = callbackURL ?? window.location.origin + window.location.pathname;
+                window.location.href = this.auth.getSocialSignInUrl(provider, target);
+            },
+            consumeSocialResult: () => {
+                if (typeof window === "undefined" || !window.location) {
+                    return { token: null, error: null };
+                }
+                const url = new URL(window.location.href);
+                const token = url.searchParams.get("token");
+                const error = url.searchParams.get("error");
+                if (token || error) {
+                    url.searchParams.delete("token");
+                    url.searchParams.delete("error");
+                    url.searchParams.delete("error_description");
+                    window.history.replaceState(null, "", url.toString());
+                }
+                return { token, error };
+            },
+        };
+    }
+    /**
+     * Identifier for the public auth endpoints: the explicit `subdomain`
+     * option, or the current hostname in browsers (the server matches it
+     * against subdomains and custom domains). App names are only unique per
+     * account, so they cannot identify an app on account-less routes.
+     */
+    authAppId() {
+        if (this.subdomain) {
+            return this.subdomain;
+        }
+        const hostname = typeof window !== "undefined" ? window.location?.hostname ?? "" : "";
+        if (!hostname ||
+            hostname === "localhost" ||
+            hostname === "127.0.0.1" ||
+            hostname === "::1" ||
+            hostname === "[::1]") {
+            throw new Error(`Cannot derive the auth app from '${hostname || "this environment"}'. ` +
+                `Pass 'subdomain' explicitly (the <app>-<account>-<hash> part of your app URL).`);
+        }
+        return hostname;
+    }
+    async request(path, init) {
+        const headers = new Headers(init?.headers);
+        if (!headers.has("Content-Type") && init?.body) {
+            headers.set("Content-Type", "application/json");
+        }
+        const response = await this.requestRaw(path, { ...init, headers });
+        const text = await response.text();
+        let parsed = null;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = { error: text };
+            }
+        }
+        return parsed;
+    }
+    async requestRaw(path, init) {
+        const headers = new Headers(init?.headers);
+        if (this.apiKey) {
+            headers.set("Authorization", `Bearer ${this.apiKey}`);
+        }
+        const response = await fetch(`${this.apiUrl}${path}`, {
+            ...init,
+            headers,
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            let parsed = null;
+            if (text) {
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    parsed = { error: text };
+                }
+            }
+            const errMessage = parsed &&
+                typeof parsed === "object" &&
+                "error" in parsed &&
+                typeof parsed.error === "string"
+                ? parsed.error
+                : `HTTP ${response.status}`;
+            throw new NofraError(errMessage, response.status);
+        }
+        return response;
+    }
+}
+export function createClient(options) {
+    return new NofraClient(options);
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@nofra/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Official JavaScript & TypeScript SDK for Nofra — No infrastructure. Just apps.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/index.ts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test src/index.test.ts"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,645 @@
+/**
+ * @nofra/sdk — Official JavaScript & TypeScript SDK for Nofra
+ * "No infrastructure. Just apps."
+ */
+
+export interface NofraClientOptions {
+  /** Name of the Nofra application (e.g. "todo-app") */
+  app: string;
+  /**
+   * App subdomain (`<app>-<account>-<hash>`) or full hostname, used for
+   * auth. Defaults to the current hostname in browsers; required on
+   * localhost and outside browsers.
+   */
+  subdomain?: string;
+  /** Control plane API URL (defaults to "https://api.nofra.net") */
+  apiUrl?: string;
+  /** Optional API token for authenticated requests */
+  apiKey?: string;
+}
+
+export type AppStatus = "running" | "deploying" | "stopped";
+
+export interface ServiceStatus {
+  name: "Compute" | "Database" | "Storage" | "Auth" | "Functions" | "Domains";
+  enabled: boolean;
+}
+
+export interface UsageMetric {
+  label: "Requests" | "Database" | "Storage" | "Bandwidth";
+  used: number;
+  limit: number;
+  unit: "req" | "GB";
+}
+
+export interface AppInfo {
+  id: string;
+  name: string;
+  url: string;
+  status: AppStatus;
+  last_deploy: string;
+  services: ServiceStatus[];
+  usage: UsageMetric[];
+}
+
+/** Creates an app with managed services available on demand. */
+export interface CreateAppOptions {
+  name: string;
+}
+
+/** Only the display URL is editable through this SDK method. */
+export interface UpdateAppOptions {
+  url?: string;
+}
+
+export interface LogEntry {
+  id: string;
+  app_name: string | null;
+  deployment_id: string | null;
+  level: "info" | "success" | "warn" | "error";
+  scope: "deploy" | "account" | "runtime";
+  message: string;
+  timestamp: string;
+}
+
+export interface UserInfo {
+  account: string;
+  username: string;
+  plan: string;
+  limits: {
+    requests: number;
+    database_gb: number;
+    storage_gb: number;
+    bandwidth_gb: number;
+  };
+}
+
+export interface DatabaseStatus {
+  app: string;
+  enabled: boolean;
+  used_gb: number;
+  limit_gb: number;
+}
+
+export interface CollectionRecord<T = Record<string, unknown>> {
+  id: string;
+  collection: string;
+  data: T;
+  created_at: string;
+}
+
+export interface CollectionFilter {
+  /** A top-level field in record data, not an SQL expression or nested path. */
+  field: string;
+  op: "eq" | "ne" | "gt" | "gte" | "lt" | "lte";
+  value: string | number | boolean | null;
+}
+
+export interface CollectionListOptions {
+  limit?: number;
+  cursor?: string;
+  filters?: CollectionFilter[];
+  sort?: "created_at" | "id" | `data.${string}`;
+  order?: "asc" | "desc";
+}
+
+export interface CollectionPage<T = Record<string, unknown>> {
+  records: CollectionRecord<T>[];
+  next_cursor: string | null;
+}
+
+export interface StorageObjectInfo {
+  key: string;
+  size: number;
+  uploaded: string;
+  /** Stored content type; absent for objects written before file support. */
+  contentType?: string;
+}
+
+export interface DatabaseRecovery {
+  id: string;
+  status: "queued" | "ready" | "failed";
+  timestamp: string | null;
+  created_at: string;
+  expires_at: string;
+  previous_available: boolean;
+  error_message: string | null;
+}
+
+export interface DatabaseRecoveryStatus {
+  platform_enabled: boolean;
+  recovery_days: number;
+  enabled: boolean;
+  active_recovery_id: string | null;
+  recoveries: DatabaseRecovery[];
+}
+
+export interface DeletedStorageObject {
+  id: string;
+  key: string;
+  size: number;
+  contentType?: string;
+  deleted_at: string;
+  expires_at: string;
+}
+
+export interface StorageTrashPage {
+  objects: DeletedStorageObject[];
+  cursor: string | null;
+  recovery_days: number;
+}
+
+/** Binary payload accepted by `storage.putFile`. */
+export type StorageFileData = Blob | ArrayBuffer | Uint8Array;
+
+export interface AppAuthUser {
+  id: string;
+  name: string;
+  email: string;
+  emailVerified: boolean;
+  createdAt: string;
+  disabled?: boolean;
+  deletion_pending?: boolean;
+}
+
+export interface AppAuthUsersPage {
+  enabled: boolean;
+  users: AppAuthUser[];
+  next_offset: number | null;
+  deletion_webhook: boolean;
+}
+
+export interface AppAuthSession {
+  id: string;
+  token: string;
+  userId: string;
+  expiresAt: string;
+}
+
+export class NofraError extends Error {
+  readonly status: number;
+
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = "NofraError";
+    this.status = status;
+  }
+}
+
+export class NofraClient {
+  readonly appName: string;
+  readonly apiUrl: string;
+  private readonly apiKey?: string;
+  private readonly subdomain?: string;
+
+  readonly app: {
+    getInfo: () => Promise<AppInfo>;
+    getLogs: () => Promise<LogEntry[]>;
+    deploy: () => Promise<{ id: string; app: string; status: string; url: string }>;
+  };
+
+  readonly apps: {
+    create: (options: CreateAppOptions) => Promise<AppInfo>;
+    update: (name: string, options: UpdateAppOptions) => Promise<AppInfo>;
+  };
+
+  readonly db: {
+    /** Pro/Team owners and admins only. Use an administrative token server-side. */
+    recovery: () => Promise<DatabaseRecoveryStatus>;
+    restore: (timestamp: string, confirm: string) => Promise<{ id: string; status: "queued" }>;
+    restorePrevious: (id: string, confirm: string) => Promise<{ id: string; status: "queued" }>;
+    status: () => Promise<DatabaseStatus>;
+    list: <T = Record<string, unknown>>(collection: string) => Promise<CollectionRecord<T>[]>;
+    listPage: <T = Record<string, unknown>>(collection: string, options?: CollectionListOptions) => Promise<CollectionPage<T>>;
+    get: <T = Record<string, unknown>>(collection: string, id: string) => Promise<CollectionRecord<T>>;
+    /** Replace the entire data value; keeps the record ID and created_at. */
+    update: <T = Record<string, unknown>>(collection: string, id: string, data: T) => Promise<CollectionRecord<T>>;
+    /** Atomically merge top-level fields. Nested values are replaced; null is stored. */
+    patch: <T = Record<string, unknown>>(collection: string, id: string, data: Partial<T>) => Promise<CollectionRecord<T>>;
+    insert: <T = Record<string, unknown>>(
+      collection: string,
+      data: T
+    ) => Promise<CollectionRecord<T>>;
+    delete: (collection: string, id: string) => Promise<{ deleted: boolean; id: string }>;
+  };
+
+  readonly storage: {
+    /** Pro/Team owners and admins only. Pass the returned cursor to read more. */
+    trash: (cursor?: string) => Promise<StorageTrashPage>;
+    restore: (id: string) => Promise<{ restored: boolean; key: string }>;
+    list: () => Promise<StorageObjectInfo[]>;
+    listPage: (cursor?: string) => Promise<{ objects: StorageObjectInfo[]; cursor: string | null }>;
+    putText: (key: string, content: string) => Promise<{ key: string; size: number }>;
+    getText: (key: string) => Promise<string>;
+    putFile: (
+      key: string,
+      data: StorageFileData,
+      contentType?: string
+    ) => Promise<{ key: string; size: number; contentType: string }>;
+    getFile: (key: string) => Promise<Blob>;
+    delete: (key: string) => Promise<{ deleted: boolean; key: string; recovery?: { id: string; expires_at: string } }>;
+  };
+
+  readonly auth: {
+    me: () => Promise<UserInfo>;
+    signUp: (params: {
+      email: string;
+      password: string;
+      name?: string;
+    }) => Promise<{ token: string | null; user: AppAuthUser }>;
+    signIn: (params: {
+      email: string;
+      password: string;
+    }) => Promise<{ token: string | null; user: AppAuthUser }>;
+    signOut: (token?: string) => Promise<{ signed_out: boolean }>;
+    getSession: (token?: string) => Promise<{
+      session: AppAuthSession | null;
+      user: AppAuthUser | null;
+    }>;
+    listUsers: (query?: string) => Promise<AppAuthUser[]>;
+    listUsersPage: (query?: string, offset?: number) => Promise<AppAuthUsersPage>;
+    setUserDisabled: (id: string, disabled: boolean) => Promise<{ disabled: boolean }>;
+    deleteUser: (id: string) => Promise<{ deleted: boolean }>;
+    /** Login types currently usable on the app (email + credentialed socials). */
+    getLoginTypes: () => Promise<{ email: boolean; social: string[] }>;
+    /** Plain-link URL that starts a social login for `provider`. */
+    getSocialSignInUrl: (provider: string, callbackURL: string) => string;
+    /** Redirects the browser to start a social login (defaults to this page). */
+    signInWithSocial: (provider: string, callbackURL?: string) => void;
+    /**
+     * Reads the social-login result (`token` or `error`) from the current URL
+     * and strips it from the address bar. Returns nulls outside the browser.
+     */
+    consumeSocialResult: () => {
+      token: string | null;
+      error: string | null;
+    };
+  };
+
+  constructor(options: NofraClientOptions) {
+    if (!options.app) {
+      throw new Error("NofraClient requires an 'app' name.");
+    }
+    this.appName = options.app;
+    this.apiUrl = (
+      options.apiUrl ?? "https://api.nofra.net"
+    ).replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.subdomain = options.subdomain;
+
+    const encodedApp = encodeURIComponent(this.appName);
+
+    this.apps = {
+      create: async (options) => {
+        const res = await this.request<{ app: AppInfo }>("/v1/apps", {
+          method: "POST",
+          body: JSON.stringify(options),
+        });
+        return res.app;
+      },
+      update: async (name, options) => {
+        const res = await this.request<{ app: AppInfo }>(`/v1/apps/${encodeURIComponent(name)}`, {
+          method: "PATCH",
+          body: JSON.stringify(options),
+        });
+        return res.app;
+      },
+    };
+
+    this.app = {
+      getInfo: async () => {
+        const res = await this.request<{ app: AppInfo }>(`/v1/apps/${encodedApp}`);
+        return res.app;
+      },
+      getLogs: async () => {
+        const res = await this.request<{ logs: LogEntry[] }>(`/v1/apps/${encodedApp}/logs`);
+        return res.logs;
+      },
+      deploy: async () => {
+        const res = await this.request<{
+          deployment: { id: string; app: string; status: string; url: string };
+        }>(`/v1/apps/${encodedApp}/deployments`, {
+          method: "POST",
+          body: JSON.stringify({}),
+        });
+        return res.deployment;
+      },
+    };
+
+    this.db = {
+      recovery: () => this.request<DatabaseRecoveryStatus>(`/v1/apps/${encodedApp}/db/recovery`),
+      restore: async (timestamp, confirm) => {
+        const response = await this.request<{ recovery: { id: string; status: "queued" } }>(
+          `/v1/apps/${encodedApp}/db/recovery`, { method: "POST", body: JSON.stringify({ timestamp, confirm }) });
+        return response.recovery;
+      },
+      restorePrevious: async (id, confirm) => {
+        const response = await this.request<{ recovery: { id: string; status: "queued" } }>(
+          `/v1/apps/${encodedApp}/db/recovery`, { method: "POST", body: JSON.stringify({ previous_id: id, confirm }) });
+        return response.recovery;
+      },
+      status: async () => {
+        const res = await this.request<{ database: DatabaseStatus }>(
+          `/v1/apps/${encodedApp}/db/status`
+        );
+        return res.database;
+      },
+      list: async <T = Record<string, unknown>>(collection: string) => {
+        const col = encodeURIComponent(collection);
+        const res = await this.request<{ records: CollectionRecord<T>[] }>(
+          `/v1/apps/${encodedApp}/db/collections/${col}`
+        );
+        return res.records;
+      },
+      listPage: <T = Record<string, unknown>>(collection: string, options: CollectionListOptions = {}) => {
+        const params = new URLSearchParams({ limit: String(options.limit ?? 100) });
+        if (options.cursor !== undefined) params.set("cursor", options.cursor);
+        if (options.filters !== undefined) params.set("filters", JSON.stringify(options.filters));
+        if (options.sort !== undefined) params.set("sort", options.sort);
+        if (options.order !== undefined) params.set("order", options.order);
+        return this.request<CollectionPage<T>>(`/v1/apps/${encodedApp}/db/collections/${encodeURIComponent(collection)}?${params}`);
+      },
+      get: async <T = Record<string, unknown>>(collection: string, id: string) => {
+        const res = await this.request<{ record: CollectionRecord<T> }>(
+          `/v1/apps/${encodedApp}/db/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`);
+        return res.record;
+      },
+      update: async <T = Record<string, unknown>>(collection: string, id: string, data: T) => {
+        const res = await this.request<{ record: CollectionRecord<T> }>(
+          `/v1/apps/${encodedApp}/db/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`,
+          { method: "PUT", body: JSON.stringify({ data }) });
+        return res.record;
+      },
+      patch: async <T = Record<string, unknown>>(collection: string, id: string, data: Partial<T>) => {
+        const res = await this.request<{ record: CollectionRecord<T> }>(
+          `/v1/apps/${encodedApp}/db/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`,
+          { method: "PATCH", body: JSON.stringify({ data }) });
+        return res.record;
+      },
+      insert: async <T = Record<string, unknown>>(collection: string, data: T) => {
+        const col = encodeURIComponent(collection);
+        const res = await this.request<{ record: CollectionRecord<T> }>(
+          `/v1/apps/${encodedApp}/db/collections/${col}`,
+          {
+            method: "POST",
+            body: JSON.stringify({ data }),
+          }
+        );
+        return res.record;
+      },
+      delete: async (collection: string, id: string) => {
+        const col = encodeURIComponent(collection);
+        const recId = encodeURIComponent(id);
+        return this.request<{ deleted: boolean; id: string }>(
+          `/v1/apps/${encodedApp}/db/collections/${col}/${recId}`,
+          { method: "DELETE" }
+        );
+      },
+    };
+
+    this.storage = {
+      listPage: (cursor) => this.request(`/v1/apps/${encodedApp}/storage${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ""}`),
+      trash: (cursor) => this.request<StorageTrashPage>(
+        `/v1/apps/${encodedApp}/storage-trash${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ""}`),
+      restore: (id) => this.request<{ restored: boolean; key: string }>(
+        `/v1/apps/${encodedApp}/storage-trash/${encodeURIComponent(id)}/restore`, { method: "POST", body: JSON.stringify({}) }),
+      list: async () => {
+        const res = await this.request<{ objects: StorageObjectInfo[] }>(
+          `/v1/apps/${encodedApp}/storage`
+        );
+        return res.objects;
+      },
+      putFile: async (key: string, data: StorageFileData, contentType?: string) => {
+        const encodedKey = encodeURIComponent(key);
+        const blobType = data instanceof Blob ? data.type : "";
+        const resolvedType =
+          contentType || blobType || "application/octet-stream";
+        // Copy views into a plain buffer: fetch types only accept ArrayBuffer-backed bodies.
+        const body: BodyInit =
+          data instanceof Uint8Array ? (data.slice().buffer as ArrayBuffer) : data;
+        return this.request<{ key: string; size: number; contentType: string }>(
+          `/v1/apps/${encodedApp}/storage/${encodedKey}?raw=1`,
+          {
+            method: "PUT",
+            headers: { "Content-Type": resolvedType },
+            body,
+          }
+        );
+      },
+      getFile: async (key: string) => {
+        const encodedKey = encodeURIComponent(key);
+        const res = await this.requestRaw(
+          `/v1/apps/${encodedApp}/storage/${encodedKey}?raw=1`
+        );
+        return res.blob();
+      },
+      putText: async (key: string, content: string) => {
+        const encodedKey = encodeURIComponent(key);
+        return this.request<{ key: string; size: number }>(
+          `/v1/apps/${encodedApp}/storage/${encodedKey}`,
+          {
+            method: "PUT",
+            body: JSON.stringify({ content }),
+          }
+        );
+      },
+      getText: async (key: string) => {
+        const encodedKey = encodeURIComponent(key);
+        const res = await this.request<{ key: string; content: string }>(
+          `/v1/apps/${encodedApp}/storage/${encodedKey}`
+        );
+        return res.content;
+      },
+      delete: async (key: string) => {
+        const encodedKey = encodeURIComponent(key);
+        return this.request<{ deleted: boolean; key: string; recovery?: { id: string; expires_at: string } }>(
+          `/v1/apps/${encodedApp}/storage/${encodedKey}`,
+          { method: "DELETE" }
+        );
+      },
+    };
+
+    this.auth = {
+      me: async () => {
+        return this.request<UserInfo>("/v1/me");
+      },
+      signUp: async (params) => {
+        const authApp = encodeURIComponent(this.authAppId());
+        return this.request<{ token: string | null; user: AppAuthUser }>(
+          `/v1/apps/${authApp}/auth/sign-up`,
+          {
+            method: "POST",
+            body: JSON.stringify(params),
+          }
+        );
+      },
+      signIn: async (params) => {
+        const authApp = encodeURIComponent(this.authAppId());
+        return this.request<{ token: string | null; user: AppAuthUser }>(
+          `/v1/apps/${authApp}/auth/sign-in`,
+          {
+            method: "POST",
+            body: JSON.stringify(params),
+          }
+        );
+      },
+      signOut: async (token) => {
+        const authApp = encodeURIComponent(this.authAppId());
+        return this.request<{ signed_out: boolean }>(
+          `/v1/apps/${authApp}/auth/sign-out`,
+          {
+            method: "POST",
+            headers: token ? { "X-Nofra-App-Token": token } : undefined,
+            body: JSON.stringify({}),
+          }
+        );
+      },
+      getSession: async (token) => {
+        const authApp = encodeURIComponent(this.authAppId());
+        return this.request<{
+          session: AppAuthSession | null;
+          user: AppAuthUser | null;
+        }>(`/v1/apps/${authApp}/auth/session`, {
+          headers: token ? { "X-Nofra-App-Token": token } : undefined,
+        });
+      },
+      listUsers: async (query = "") => {
+        const res = await this.request<{ enabled: boolean; users: AppAuthUser[] }>(
+          `/v1/apps/${encodedApp}/auth/users?q=${encodeURIComponent(query)}&offset=0`
+        );
+        return res.users;
+      },
+      listUsersPage: (query = "", offset = 0) =>
+        this.request<AppAuthUsersPage>(`/v1/apps/${encodedApp}/auth/users?q=${encodeURIComponent(query)}&offset=${offset}`),
+      setUserDisabled: (id, disabled) =>
+        this.request(`/v1/apps/${encodedApp}/auth/users/${encodeURIComponent(id)}`, { method: "PATCH", body: JSON.stringify({ disabled }) }),
+      deleteUser: (id) =>
+        this.request(`/v1/apps/${encodedApp}/auth/users/${encodeURIComponent(id)}`, { method: "DELETE", body: JSON.stringify({ confirm: id }) }),
+      getLoginTypes: async () => {
+        const authApp = encodeURIComponent(this.authAppId());
+        return this.request<{ email: boolean; social: string[] }>(
+          `/v1/apps/${authApp}/auth/config`
+        );
+      },
+      getSocialSignInUrl: (provider, callbackURL) => {
+        const authApp = encodeURIComponent(this.authAppId());
+        return (
+          `${this.apiUrl}/v1/apps/${authApp}/auth/social-start` +
+          `?provider=${encodeURIComponent(provider)}` +
+          `&to=${encodeURIComponent(callbackURL)}`
+        );
+      },
+      signInWithSocial: (provider, callbackURL) => {
+        if (typeof window === "undefined" || !window.location) {
+          throw new Error(
+            "signInWithSocial needs a browser. Use getSocialSignInUrl() to build the link instead."
+          );
+        }
+        const target =
+          callbackURL ?? window.location.origin + window.location.pathname;
+        window.location.href = this.auth.getSocialSignInUrl(provider, target);
+      },
+      consumeSocialResult: () => {
+        if (typeof window === "undefined" || !window.location) {
+          return { token: null, error: null };
+        }
+        const url = new URL(window.location.href);
+        const token = url.searchParams.get("token");
+        const error = url.searchParams.get("error");
+        if (token || error) {
+          url.searchParams.delete("token");
+          url.searchParams.delete("error");
+          url.searchParams.delete("error_description");
+          window.history.replaceState(null, "", url.toString());
+        }
+        return { token, error };
+      },
+    };
+  }
+
+  /**
+   * Identifier for the public auth endpoints: the explicit `subdomain`
+   * option, or the current hostname in browsers (the server matches it
+   * against subdomains and custom domains). App names are only unique per
+   * account, so they cannot identify an app on account-less routes.
+   */
+  private authAppId(): string {
+    if (this.subdomain) {
+      return this.subdomain;
+    }
+    const hostname =
+      typeof window !== "undefined" ? window.location?.hostname ?? "" : "";
+    if (
+      !hostname ||
+      hostname === "localhost" ||
+      hostname === "127.0.0.1" ||
+      hostname === "::1" ||
+      hostname === "[::1]"
+    ) {
+      throw new Error(
+        `Cannot derive the auth app from '${hostname || "this environment"}'. ` +
+          `Pass 'subdomain' explicitly (the <app>-<account>-<hash> part of your app URL).`
+      );
+    }
+    return hostname;
+  }
+
+  private async request<T>(path: string, init?: RequestInit): Promise<T> {
+    const headers = new Headers(init?.headers);
+    if (!headers.has("Content-Type") && init?.body) {
+      headers.set("Content-Type", "application/json");
+    }
+
+    const response = await this.requestRaw(path, { ...init, headers });
+
+    const text = await response.text();
+    let parsed: unknown = null;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = { error: text };
+      }
+    }
+
+    return parsed as T;
+  }
+
+  private async requestRaw(path: string, init?: RequestInit): Promise<Response> {
+    const headers = new Headers(init?.headers);
+    if (this.apiKey) {
+      headers.set("Authorization", `Bearer ${this.apiKey}`);
+    }
+
+    const response = await fetch(`${this.apiUrl}${path}`, {
+      ...init,
+      headers,
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      let parsed: unknown = null;
+      if (text) {
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = { error: text };
+        }
+      }
+      const errMessage =
+        parsed &&
+        typeof parsed === "object" &&
+        "error" in parsed &&
+        typeof (parsed as { error: unknown }).error === "string"
+          ? (parsed as { error: string }).error
+          : `HTTP ${response.status}`;
+      throw new NofraError(errMessage, response.status);
+    }
+
+    return response;
+  }
+}
+
+export function createClient(options: NofraClientOptions): NofraClient {
+  return new NofraClient(options);
+}