@wtfalch/edge 0.0.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Tallis Falch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,48 @@
 # @wtfalch/edge
 
-Placeholder. Use 0.1.0 or later.
+Public client SDK and API types for the edge service. Requires Node 22+ or a
+browser with Fetch support. The client has no runtime package dependencies.
+
+## Status
+
+Published: yes, v0.3.0, 2026-10-06.
+
+```sh
+npm install @wtfalch/edge
+```
+
+```ts
+import { createEdgeClient } from '@wtfalch/edge';
+
+const edge = createEdgeClient({
+  url: process.env.EDGE_URL,
+  apiKey: process.env.EDGE_API_KEY,
+});
+
+if ((await edge.available('alice')).available) {
+  const claim = await edge.claim({ name: 'alice', port: 8080, ref: 'device-1' });
+  const { token } = await edge.token(claim.id); // hand to the user's machine
+}
+```
+
+```ts
+// DNS records under the org's domain (`records:read`, `records:edit`)
+const { records } = await edge.records.list();
+const www = await edge.records.create({ label: 'www', type: 'A', content: '203.0.113.7' });
+await edge.records.update(www.id, { ttl: 300 });
+await edge.records.remove(www.id);
+```
+
+The key carries the organisation and the one domain its names live under, so
+no call names either. `claim` is safe to repeat: the same `ref` returns the same
+claim, and a new `port` moves its route. `get(ref)` finds the claim for a `ref` without listing. `close` makes the name answer 404 and
+keeps it claimed; `remove` deletes the tunnel and record. `setReservedLabels`,
+`mintKey` and `revokeKey` need the platform credential and are refused for an
+entry key. A `remove` that already happened succeeds again, so a lost response is safe to retry. `rate_limited` errors carry `retryAfterSeconds`; a `conflict` with `reason: 'upstream_rejected'` means Cloudflare permanently refused, so do not retry it. `records.list()` also shows the zone's other records as `owner: 'platform'`, `locked: true`; they are never changed through edge. `records.create` takes `label` (`@` for the apex, TXT only), `type` (TXT, MX, CNAME, A, AAAA, CAA) and `content`, or `data` for CAA. `records.update` changes `content`, `data`, `ttl` or `priority`; to change a label or type, remove the record and create another. A records `conflict` carries a `reason` of `busy`, `pending`, `removing`, `taken` or `upstream_rejected` (`RecordConflictReason`); a record the platform owns answers `forbidden`, and the org's records cap answers `over_budget`. API failures reject with `EdgeApiError`, which carries `status` and
+a typed `code` (see `EdgeError`); the SDK never throws a bare `Error` for a
+service failure.
+
+The root export provides the client and public request/response types.
+`@wtfalch/edge/client` is also supported. There are no server, database,
+migration or authorization exports. The service implementation is a private
+package.

package/dist/client.d.ts

@@ -0,0 +1,49 @@
+import { type ClientOptions } from './transport.js';
+import type { AvailableResponse, ClaimNameRequest, ListClaimsResponse, ListRecordsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OrgSettingsRequest, RecordInput, RecordPatch, RecordView, TokenResponse } from './types.js';
+export { EdgeApiError, type ClientOptions } from './transport.js';
+/** Called with an entry's key: the key carries its organisation and domain, so
+ * no call names either. `setReservedLabels`, `mintKey` and `revokeKey` are
+ * refused by the service for any credential but the platform's own. */
+export declare function createEdgeClient(options: ClientOptions): {
+    /** The org's DNS records. Needs `records:read` (`records:edit` for changes). */
+    records: {
+        /** The org's own records, then every other live record in the zone as a
+         * locked platform record. */
+        list: () => Promise<ListRecordsResponse>;
+        /** Rejects with `not_found` when there is no such record. */
+        get: (id: string) => Promise<RecordView>;
+        /** Rejects with `conflict` (see `RecordConflictReason`) when the record
+         * exists or clashes, `forbidden` for a platform-owned label, and
+         * `over_budget` at the org's records cap. */
+        create: (input: RecordInput) => Promise<RecordView>;
+        /** Changes content, ttl or priority of the org's own record. */
+        update: (id: string, patch: RecordPatch) => Promise<RecordView>;
+        /** Returns the tombstone (`state: 'removed'`); repeating it is safe. */
+        remove: (id: string) => Promise<RecordView>;
+    };
+    /** True when the name is free: not reserved, no record in the zone, not claimed. */
+    available: (name: string) => Promise<AvailableResponse>;
+    /** Creates the tunnel, routes `name` to `127.0.0.1:<port>` with a 404
+     * catch-all, publishes the proxied CNAME. Safe to repeat: the same `ref`
+     * returns the same claim, moving its route when `port` changed. */
+    claim: (input: ClaimNameRequest) => Promise<NameClaim>;
+    /** The org's own claim for `ref`, so a caller can find it without `list()`.
+     * Rejects with `not_found` when there is none. */
+    get: (ref: string) => Promise<NameClaim>;
+    /** Returns the tunnel token for the app to hand to its user's machine. */
+    token: (id: string) => Promise<TokenResponse>;
+    /** The tunnel answers 404 at once; the name stays claimed. */
+    close: (id: string) => Promise<NameClaim>;
+    /** Drops connections, deletes the record and the tunnel. */
+    remove: (id: string) => Promise<NameClaim>;
+    /** The org's claims with their state. */
+    list: () => Promise<ListClaimsResponse>;
+    /** Platform credential only: replaces an org's reserved labels. */
+    setReservedLabels: (organisationId: string, labels: string[]) => Promise<void>;
+    /** Platform credential only: the org's claim cap and rate bucket. */
+    setOrgSettings: (input: OrgSettingsRequest) => Promise<void>;
+    /** Platform credential only: mints an entry key for an org. */
+    mintKey: (input: MintKeyRequest) => Promise<MintKeyResponse>;
+    /** Platform credential only: revokes an entry key. */
+    revokeKey: (organisationId: string, id: string) => Promise<void>;
+};

package/dist/client.js

@@ -0,0 +1,51 @@
+import { createTransport } from './transport.js';
+export { EdgeApiError } from './transport.js';
+/** Called with an entry's key: the key carries its organisation and domain, so
+ * no call names either. `setReservedLabels`, `mintKey` and `revokeKey` are
+ * refused by the service for any credential but the platform's own. */
+export function createEdgeClient(options) {
+    const call = createTransport(options);
+    return {
+        /** The org's DNS records. Needs `records:read` (`records:edit` for changes). */
+        records: {
+            /** The org's own records, then every other live record in the zone as a
+             * locked platform record. */
+            list: () => call('GET', '/v1/records'),
+            /** Rejects with `not_found` when there is no such record. */
+            get: (id) => call('GET', `/v1/records/${encodeURIComponent(id)}`),
+            /** Rejects with `conflict` (see `RecordConflictReason`) when the record
+             * exists or clashes, `forbidden` for a platform-owned label, and
+             * `over_budget` at the org's records cap. */
+            create: (input) => call('POST', '/v1/records', input),
+            /** Changes content, ttl or priority of the org's own record. */
+            update: (id, patch) => call('PATCH', `/v1/records/${encodeURIComponent(id)}`, patch),
+            /** Returns the tombstone (`state: 'removed'`); repeating it is safe. */
+            remove: (id) => call('DELETE', `/v1/records/${encodeURIComponent(id)}`),
+        },
+        /** True when the name is free: not reserved, no record in the zone, not claimed. */
+        available: (name) => call('GET', `/v1/names/available?${new URLSearchParams({ name })}`),
+        /** Creates the tunnel, routes `name` to `127.0.0.1:<port>` with a 404
+         * catch-all, publishes the proxied CNAME. Safe to repeat: the same `ref`
+         * returns the same claim, moving its route when `port` changed. */
+        claim: (input) => call('POST', '/v1/names/claims', input),
+        /** The org's own claim for `ref`, so a caller can find it without `list()`.
+         * Rejects with `not_found` when there is none. */
+        get: (ref) => call('GET', `/v1/names/claim?${new URLSearchParams({ ref })}`),
+        /** Returns the tunnel token for the app to hand to its user's machine. */
+        token: (id) => call('GET', `/v1/names/claims/${encodeURIComponent(id)}/token`),
+        /** The tunnel answers 404 at once; the name stays claimed. */
+        close: (id) => call('POST', `/v1/names/claims/${encodeURIComponent(id)}/close`, {}),
+        /** Drops connections, deletes the record and the tunnel. */
+        remove: (id) => call('DELETE', `/v1/names/claims/${encodeURIComponent(id)}`),
+        /** The org's claims with their state. */
+        list: () => call('GET', '/v1/names/claims'),
+        /** Platform credential only: replaces an org's reserved labels. */
+        setReservedLabels: (organisationId, labels) => call('PUT', '/v1/names/reserved-labels', { organisationId, labels }),
+        /** Platform credential only: the org's claim cap and rate bucket. */
+        setOrgSettings: (input) => call('PUT', '/v1/names/settings', input),
+        /** Platform credential only: mints an entry key for an org. */
+        mintKey: (input) => call('POST', '/v1/names/keys', input),
+        /** Platform credential only: revokes an entry key. */
+        revokeKey: (organisationId, id) => call('DELETE', `/v1/names/keys/${encodeURIComponent(id)}?${new URLSearchParams({ organisationId })}`),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './client.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './client.js';

package/dist/transport.d.ts

@@ -0,0 +1,23 @@
+import type { EdgeConflictReason, EdgeErrorCode } from './types.js';
+export interface ClientOptions {
+    /** The edge service's address (foundry's `EDGE_URL`). */
+    url: string;
+    /** The entry's key (foundry's `EDGE_API_KEY`), or the platform credential. */
+    apiKey: string;
+    fetch?: typeof fetch;
+}
+/** A typed failure, never a bare `Error`. `status` is the HTTP status; `code`
+ * and `message` are the service's own wire error (see `EdgeError`). */
+export declare class EdgeApiError extends Error {
+    readonly status: number;
+    readonly code: EdgeErrorCode;
+    readonly retryAfterSeconds?: number | undefined;
+    /** Set on every `conflict`. */
+    readonly reason?: EdgeConflictReason | undefined;
+    constructor(status: number, code: EdgeErrorCode, message: string, retryAfterSeconds?: number | undefined, 
+    /** Set on every `conflict`. */
+    reason?: EdgeConflictReason | undefined);
+}
+/** Minimal fetch-based transport: JSON in, JSON out, a bearer credential on
+ * every request. No Node-only imports -- this runs in a browser too. */
+export declare function createTransport(options: ClientOptions): <T>(method: string, path: string, input?: unknown) => Promise<T>;

package/dist/transport.js

@@ -0,0 +1,84 @@
+const KNOWN_CODES = [
+    'invalid_request',
+    'unauthorized',
+    'forbidden',
+    'not_found',
+    'conflict',
+    'over_budget',
+    'rate_limited',
+    'not_configured',
+    'unavailable',
+];
+/** A typed failure, never a bare `Error`. `status` is the HTTP status; `code`
+ * and `message` are the service's own wire error (see `EdgeError`). */
+export class EdgeApiError extends Error {
+    status;
+    code;
+    retryAfterSeconds;
+    reason;
+    constructor(status, code, message, retryAfterSeconds, 
+    /** Set on every `conflict`. */
+    reason) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.reason = reason;
+        this.name = 'EdgeApiError';
+    }
+}
+function errorFrom(value) {
+    const error = typeof value === 'object' && value !== null && 'error' in value
+        ? value.error
+        : null;
+    const rawCode = typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string'
+        ? error.code
+        : undefined;
+    const rawMessage = typeof error === 'object' &&
+        error !== null &&
+        'message' in error &&
+        typeof error.message === 'string'
+        ? error.message
+        : undefined;
+    const code = KNOWN_CODES.includes(rawCode ?? '')
+        ? rawCode
+        : 'unavailable';
+    const rawReason = typeof error === 'object' &&
+        error !== null &&
+        'reason' in error &&
+        typeof error.reason === 'string'
+        ? error.reason
+        : undefined;
+    return {
+        code,
+        message: rawMessage ?? 'Request failed',
+        reason: rawReason,
+    };
+}
+/** Minimal fetch-based transport: JSON in, JSON out, a bearer credential on
+ * every request. No Node-only imports -- this runs in a browser too. */
+export function createTransport(options) {
+    return async (method, path, input) => {
+        const response = await (options.fetch ?? fetch)(new URL(path.replace(/^\//, ''), options.url.endsWith('/') ? options.url : `${options.url}/`), {
+            method,
+            headers: {
+                authorization: `Bearer ${options.apiKey}`,
+                ...(input === undefined ? {} : { 'content-type': 'application/json' }),
+            },
+            body: input === undefined ? undefined : JSON.stringify(input),
+        });
+        let value;
+        try {
+            value = response.status === 204 ? undefined : await response.json();
+        }
+        catch {
+            throw new EdgeApiError(response.status, 'unavailable', 'Invalid response body');
+        }
+        if (!response.ok) {
+            const { code, message, reason } = errorFrom(value);
+            const retryAfter = Number(response.headers.get('retry-after'));
+            throw new EdgeApiError(response.status, code, message, Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : undefined, reason);
+        }
+        return value;
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,159 @@
+/** Public HTTP contracts for the edge service. Internal storage rows --
+ * the Cloudflare tunnel and DNS record ids -- are never returned. */
+export interface NameClaim {
+    id: string;
+    organisationId: string;
+    /** The DNS label, under the calling organisation's own domain. */
+    name: string;
+    /** `<name>.<the organisation's domain>` -- what the SDK calls `claim()`
+     * with and what the service actually resolved it to is always the same
+     * string, since the domain is never caller-supplied. */
+    hostname: string;
+    port: number;
+    /** The caller-chosen idempotency key passed to `claim()`. */
+    ref: string;
+    /** `pending`: still being set up (claim the same `ref` again to finish it).
+     * `removing`: teardown started (call `remove` again). `removed`: the
+     * tombstone `remove` returns, so a retried remove succeeds. */
+    state: 'pending' | 'active' | 'closed' | 'removing' | 'removed';
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AvailableResponse {
+    available: boolean;
+}
+export interface ClaimNameRequest {
+    name: string;
+    port: number;
+    ref: string;
+}
+export interface TokenResponse {
+    token: string;
+}
+export interface ListClaimsResponse {
+    claims: NameClaim[];
+}
+export interface SetReservedLabelsRequest {
+    organisationId: string;
+    labels: string[];
+}
+/** The wire shape of a failed request, discriminated on `code` so a caller
+ * can narrow on it. Every non-2xx response body has this shape. */
+export type EdgeError = {
+    code: 'invalid_request';
+    message: string;
+} | {
+    code: 'unauthorized';
+    message: string;
+} | {
+    code: 'forbidden';
+    message: string;
+} | {
+    code: 'not_found';
+    message: string;
+} | {
+    code: 'conflict';
+    message: string;
+} | {
+    code: 'over_budget';
+    message: string;
+} | {
+    code: 'rate_limited';
+    message: string;
+} | {
+    code: 'not_configured';
+    message: string;
+} | {
+    code: 'unavailable';
+    message: string;
+};
+/** `reason: 'upstream_rejected'` on a `conflict` means Cloudflare permanently
+ * refused the request: retrying will not help. `unavailable` and
+ * `rate_limited` are the retryable ones. */
+export type EdgeErrorCode = EdgeError['code'];
+/** Platform credential only: mints an entry key for an org. */
+export interface MintKeyRequest {
+    organisationId: string;
+    /** The one domain this key's names may live under. */
+    domain: string;
+    name: string;
+    expiresDays?: number;
+}
+export interface MintKeyResponse {
+    id: string;
+    /** Shown once; the service stores only its hash. */
+    secret: string;
+}
+/** Platform credential only. A null or omitted field clears that override and
+ * the service default applies again. */
+export interface OrgSettingsRequest {
+    organisationId: string;
+    /** Most live claims (pending, active, closed) this org may hold. */
+    maxClaims?: number | null;
+    /** Most live DNS records this org may hold. */
+    maxRecords?: number | null;
+    /** Rate bucket: calls allowed in a burst. */
+    rateBurst?: number | null;
+    /** Rate bucket: calls refilled per second. */
+    ratePerSecond?: number | null;
+}
+/** Why a `conflict` happened. `busy`: another call holds this claim, retry
+ * soon. `pending`: still being set up. `removing`: teardown in progress, retry
+ * the remove. `taken`: the name or ref belongs to something else; do not
+ * retry. `held`: the name was removed less than 30 days ago; do not retry
+ * until the hold ends. `upstream_rejected`: Cloudflare permanently refused; do not retry. */
+export type EdgeConflictReason = 'busy' | 'pending' | 'removing' | 'taken' | 'held' | 'upstream_rejected';
+export type RecordType = 'TXT' | 'MX' | 'CNAME' | 'A' | 'AAAA' | 'CAA';
+/** CAA's structured value, in Cloudflare's form. */
+export interface CaaData {
+    flags: number;
+    tag: string;
+    value: string;
+}
+/** A DNS record in the organisation's zone. The org's own records have
+ * `owner: 'organisation'`; every other live record in the zone is shown as
+ * `owner: 'platform'` with `locked: true` and is never changed through edge. */
+export interface RecordView {
+    /** The row id for the org's own record; Cloudflare's id for a platform one. */
+    id: string;
+    /** The label under the org's domain; the apex is `@`. */
+    label: string;
+    type: string;
+    content: string;
+    /** Seconds, or 1 for automatic. */
+    ttl: number;
+    /** MX only; null otherwise. */
+    priority: number | null;
+    owner: 'organisation' | 'platform';
+    locked: boolean;
+    /** `pending`: still being set up. `removing`: teardown started. `removed`:
+     * the tombstone `records.remove` returns. */
+    state: 'pending' | 'active' | 'removing' | 'removed';
+}
+export interface RecordInput {
+    label: string;
+    type: RecordType;
+    /** Every type but CAA. */
+    content?: string;
+    /** CAA only. */
+    data?: CaaData;
+    /** Seconds (60 to 86400), or 1 for automatic (the default). */
+    ttl?: number;
+    /** MX only, 0 to 65535. */
+    priority?: number;
+}
+/** The label and type never change: remove the record and create another. */
+export interface RecordPatch {
+    content?: string;
+    data?: CaaData;
+    ttl?: number;
+    priority?: number;
+}
+export interface ListRecordsResponse {
+    records: RecordView[];
+}
+/** Why a records call answered `conflict`: `busy` (retry soon), `pending`
+ * (still being set up), `removing` (teardown in progress), or `taken` (the
+ * record, or one it clashes with, already exists; do not retry), or `upstream_rejected`
+ * (Cloudflare permanently refused; do not retry). */
+export type RecordConflictReason = Extract<EdgeConflictReason, 'busy' | 'pending' | 'removing' | 'taken' | 'upstream_rejected'>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,52 @@
 {
   "name": "@wtfalch/edge",
-  "version": "0.0.0",
-  "description": "Placeholder that claims the name. Real releases start at 0.1.0.",
+  "version": "0.3.0",
+  "type": "module",
   "license": "MIT",
-  "repository": { "type": "git", "url": "https://github.com/wtfalch/edge" }
+  "description": "Public client SDK and API types for the edge service.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wtfalch/edge",
+    "directory": "packages/sdk"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist/client.d.ts",
+    "dist/client.js",
+    "dist/index.d.ts",
+    "dist/index.js",
+    "dist/transport.d.ts",
+    "dist/transport.js",
+    "dist/types.d.ts",
+    "dist/types.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    }
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm build && node ../../scripts/check-package.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.6"
+  }
 }