@freeholder/sdk 0.0.0-stage → 0.2.0-beta.3

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { PLATFORM_VERSION } from "./version.ts";
+import type { FreeholderApi, PageableService, ServiceInput, ServiceName, ServiceOutput } from "./generated.ts";
+export { PLATFORM_VERSION };
+export { PAGEABLE_SERVICES, SERVICE_NAMES, type FreeholderApi, type PageableService, type ServiceCatalog, type ServiceInput, type ServiceName, type ServiceOutput, } from "./generated.ts";
+export declare class FreeholderError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export interface FreeholderClientOptions {
+    /** Instance origin, no trailing slash. */
+    baseUrl: string;
+    /** API key from Settings. Omit for public services. */
+    token?: string;
+    fetch?: typeof fetch;
+}
+type OptionalInputService = {
+    [K in ServiceName]: Record<string, never> extends ServiceInput<K> ? K : never;
+}[ServiceName];
+type PageItem<K extends PageableService> = ServiceOutput<K> extends {
+    rows: Array<infer Item>;
+} ? Item : never;
+export declare class FreeholderClient {
+    readonly version = "0.2.0-beta.3";
+    private readonly baseUrl;
+    private readonly token?;
+    private readonly fetchImpl;
+    constructor(options: FreeholderClientOptions);
+    /** A client that presents a different API key on the same origin. */
+    withToken(token: string): FreeholderClient;
+    /**
+     * Namespaced methods for every service in the published catalog.
+     * Instance-specific plugin verbs still go through `call(name, input)`.
+     */
+    get api(): FreeholderApi;
+    call<K extends OptionalInputService>(name: K, input?: ServiceInput<K>): Promise<ServiceOutput<K>>;
+    call<K extends ServiceName>(name: K, input: ServiceInput<K>): Promise<ServiceOutput<K>>;
+    call(name: string, input?: unknown): Promise<unknown>;
+    /**
+     * Walk a `{ rows, total }` list until every row is yielded.
+     * Only services in `PAGEABLE_SERVICES` accept this wrapper.
+     */
+    paginate<K extends PageableService>(name: K, input: Omit<ServiceInput<K>, "offset">): AsyncGenerator<PageItem<K>>;
+    private request;
+}
+export declare function createClient(options: FreeholderClientOptions): FreeholderClient;

package/dist/index.js

@@ -0,0 +1,110 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Typed HTTP client for a Freeholder instance (MASTER.md §28, C3.03).
+//
+// Concrete methods and input/output types are generated from the live
+// service registry. Transport, auth and pagination wrappers live here and
+// are typed against that generated layer so a contract change breaks them.
+import { PLATFORM_VERSION } from "./version.js";
+export { PLATFORM_VERSION };
+export { PAGEABLE_SERVICES, SERVICE_NAMES, } from "./generated.js";
+const SERVICE_NAME = /^[a-z][a-zA-Z0-9]*\.[a-zA-Z0-9]+$/;
+export class FreeholderError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "FreeholderError";
+    }
+}
+export class FreeholderClient {
+    version = PLATFORM_VERSION;
+    baseUrl;
+    token;
+    fetchImpl;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.token = options.token;
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    /** A client that presents a different API key on the same origin. */
+    withToken(token) {
+        return new FreeholderClient({
+            baseUrl: this.baseUrl,
+            token,
+            fetch: this.fetchImpl,
+        });
+    }
+    /**
+     * Namespaced methods for every service in the published catalog.
+     * Instance-specific plugin verbs still go through `call(name, input)`.
+     */
+    get api() {
+        return createApiProxy((name, input) => this.request(name, input));
+    }
+    async call(name, input = {}) {
+        return this.request(name, input);
+    }
+    /**
+     * Walk a `{ rows, total }` list until every row is yielded.
+     * Only services in `PAGEABLE_SERVICES` accept this wrapper.
+     */
+    async *paginate(name, input) {
+        let offset = 0;
+        for (;;) {
+            const page = (await this.call(name, { ...input, offset }));
+            for (const row of page.rows)
+                yield row;
+            offset += page.rows.length;
+            if (page.rows.length === 0 || offset >= page.total)
+                break;
+        }
+    }
+    async request(service, input = {}) {
+        if (!SERVICE_NAME.test(service)) {
+            throw new FreeholderError(400, "validation", `Not a service name: ${service}`);
+        }
+        const headers = {
+            accept: "application/json",
+            "content-type": "application/json",
+        };
+        if (this.token)
+            headers.authorization = `Bearer ${this.token}`;
+        const response = await this.fetchImpl(`${this.baseUrl}/api/v1/${service}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(input ?? {}),
+        });
+        const body = (await response.json().catch(() => ({})));
+        if (!response.ok) {
+            throw new FreeholderError(response.status, body.error?.code ?? "internal", body.error?.message ?? `HTTP ${response.status}`);
+        }
+        return body;
+    }
+}
+export function createClient(options) {
+    return new FreeholderClient(options);
+}
+function createApiProxy(request) {
+    const families = new Map();
+    return new Proxy({}, {
+        get(_target, family) {
+            if (typeof family !== "string" || family === "then")
+                return undefined;
+            let methods = families.get(family);
+            if (!methods) {
+                methods = new Proxy({}, {
+                    get(_inner, verb) {
+                        if (typeof verb !== "string" || verb === "then")
+                            return undefined;
+                        return (input = {}) => request(`${family}.${verb}`, input);
+                    },
+                });
+                families.set(family, methods);
+            }
+            return methods;
+        },
+    });
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const PLATFORM_VERSION = "0.2.0-beta.3";

package/dist/version.js

@@ -0,0 +1,4 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Kept in lockstep with the platform package.json version (C3.20).
+export const PLATFORM_VERSION = "0.2.0-beta.3";

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@freeholder/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-beta.3",
+  "description": "Typed HTTP client for a Freeholder instance, generated from the live service registry",
+  "license": "Apache-2.0",
+  "author": "Tony Aly <tony@paradisemodern.com> (https://tonyaly.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CampDenman/freeholder.git",
+    "directory": "packages/sdk"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test test/*.test.mjs"
+  }
 }