@wtfalch/edge 0.5.1 → 0.7.0

package/README.md

@@ -61,6 +61,17 @@ await edge.platform.tunnels.putConfig(tunnel.id, {
 const { token } = await edge.platform.tunnels.token(tunnel.id);
 ```
 
+```ts
+// With the platform credential only: an Access app and its policy
+const app = await edge.platform.access.create({ name: 'gate', domain: 'app.acme.com' });
+await edge.platform.access.createPolicy(app.id, {
+  name: 'staff',
+  decision: 'allow',
+  include: [{ email: { email: 'a@acme.com' } }],
+});
+const { token } = await edge.platform.access.findServiceToken('ci'); // id and name, never a secret
+```
+
 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

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type ClientOptions } from './transport.js';
-import type { AdoptRecordsRequest, AdoptRecordsResponse, AdoptTunnelsRequest, AdoptTunnelsResponse, AvailableResponse, ClaimNameRequest, CreatePlatformRecordRequest, CreatePlatformTunnelRequest, ListClaimsResponse, ListPlatformRecordsRequest, ListPlatformRecordsResponse, ListPlatformTunnelsResponse, ListRecordsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OrgSettingsRequest, PlatformRecordView, PlatformTunnelView, PutPlatformTunnelConfigRequest, RecordInput, RecordPatch, RecordView, TokenResponse, UpdatePlatformRecordRequest } from './types.js';
+import type { AdoptAccessAppsRequest, AdoptAccessAppsResponse, AdoptRecordsRequest, AdoptRecordsResponse, AdoptTunnelsRequest, AdoptTunnelsResponse, AdoptWorkersRequest, AdoptWorkersResponse, AvailableResponse, ClaimNameRequest, CreatePlatformAccessAppRequest, CreatePlatformAccessPolicyRequest, CreatePlatformRecordRequest, CreatePlatformTunnelRequest, CreatePlatformWorkerRouteRequest, FindServiceTokenResponse, ListClaimsResponse, ListPlatformAccessAppsRequest, ListPlatformAccessAppsResponse, ListPlatformAccessPoliciesResponse, ListPlatformRecordsRequest, ListPlatformRecordsResponse, ListPlatformTunnelsResponse, ListPlatformWorkerRoutesRequest, ListPlatformWorkerRoutesResponse, ListPlatformWorkerScriptsResponse, ListRecordsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OrgSettingsRequest, PlatformAccessAppView, PlatformAccessPolicyView, PlatformRecordView, PlatformTunnelView, PlatformWorkerRouteView, PlatformWorkerScriptView, PutPlatformTunnelConfigRequest, RecordInput, RecordPatch, RecordView, TokenResponse, UpdatePlatformRecordRequest, UploadPlatformWorkerScriptRequest } 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
@@ -61,6 +61,58 @@ export declare function createEdgeClient(options: ClientOptions): {
              * or recreated, and a tunnel nobody names is left alone. */
             adopt: (input: AdoptTunnelsRequest) => Promise<AdoptTunnelsResponse>;
         };
+        /** Cloudflare Access applications the platform owns, and their policies.
+         * `id` is Cloudflare's app id. */
+        access: {
+            /** Every live app with its owner (`null`: no row), optionally narrowed
+             * by exact `domain` and/or `name`. */
+            list: (filter?: ListPlatformAccessAppsRequest) => Promise<ListPlatformAccessAppsResponse>;
+            /** Creates the app, or returns the one edge already made for that
+             * domain and name. Rejects with `conflict` when a live app holds the
+             * domain that nobody adopted (adopt it instead). */
+            create: (input: CreatePlatformAccessAppRequest) => Promise<PlatformAccessAppView>;
+            /** Deletes the app; returns the tombstone. Repeating it rejects with `not_found`. */
+            remove: (id: string) => Promise<PlatformAccessAppView>;
+            /** The policies on an app the platform owns. */
+            listPolicies: (appId: string) => Promise<ListPlatformAccessPoliciesResponse>;
+            /** Adds a policy. The same name with the same content returns it as it
+             * is (safe to repeat); the same name with other content rejects with `conflict`. */
+            createPolicy: (appId: string, input: CreatePlatformAccessPolicyRequest) => Promise<PlatformAccessPolicyView>;
+            /** A service token's id by exact name; `token` is `null` when none has
+             * it. Read-only: the secret is never returned. */
+            findServiceToken: (name: string) => Promise<FindServiceTokenResponse>;
+            /** Writes platform rows for the live apps named. Nothing is deleted or
+             * recreated, and an app nobody names is left alone. */
+            adopt: (input: AdoptAccessAppsRequest) => Promise<AdoptAccessAppsResponse>;
+        };
+        /** Cloudflare Workers scripts and routes the platform owns. A script's
+         * `id` is its name; a route's `id` is Cloudflare's route id. */
+        workers: {
+            /** Every live script with its owner (`null`: no row), optionally only the one named `name`. */
+            listScripts: (filter?: {
+                name?: string;
+            }) => Promise<ListPlatformWorkerScriptsResponse>;
+            /** Uploads the script (base64, at most 10 MB), or redeploys the one edge
+             * already owns (201 on the first upload, 200 after). Rejects with
+             * `conflict` when a live script of that name exists that nobody adopted
+             * (adopt it instead) or another upload of the name is in progress, and
+             * with `invalid_request` when the script is not base64 or its sha256
+             * differs from `artifactSha256`. */
+            uploadScript: (name: string, input: UploadPlatformWorkerScriptRequest) => Promise<PlatformWorkerScriptView>;
+            /** Deletes the script; returns the tombstone. Repeating it rejects with `not_found`. */
+            removeScript: (name: string) => Promise<PlatformWorkerScriptView>;
+            /** Every live route in the zone with its owner (`null`: no row), optionally only one pattern. */
+            listRoutes: (filter: ListPlatformWorkerRoutesRequest) => Promise<ListPlatformWorkerRoutesResponse>;
+            /** Creates the route, or returns the one edge already made for that
+             * zone, pattern and script. Rejects with `conflict` when a live route
+             * holds the pattern that nobody adopted (adopt it instead). */
+            createRoute: (input: CreatePlatformWorkerRouteRequest) => Promise<PlatformWorkerRouteView>;
+            /** Deletes the route in `zoneId`; returns the tombstone. Repeating it rejects with `not_found`. */
+            removeRoute: (zoneId: string, id: string) => Promise<PlatformWorkerRouteView>;
+            /** Writes platform rows for the scripts and routes named. Nothing is
+             * deleted or recreated, and anything nobody names is left alone. */
+            adopt: (input: AdoptWorkersRequest) => Promise<AdoptWorkersResponse>;
+        };
     };
     /** True when the name is free: not reserved, no record in the zone, not claimed. */
     available: (name: string) => Promise<AvailableResponse>;

package/dist/client.js

@@ -1,5 +1,9 @@
 import { createTransport } from './transport.js';
 export { EdgeApiError } from './transport.js';
+function query(values) {
+    const search = new URLSearchParams(Object.entries(values).filter((entry) => entry[1] !== undefined)).toString();
+    return search === '' ? '' : `?${search}`;
+}
 /** 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. */
@@ -60,6 +64,56 @@ export function createEdgeClient(options) {
                  * or recreated, and a tunnel nobody names is left alone. */
                 adopt: (input) => call('POST', '/v1/platform/tunnels/adopt', input),
             },
+            /** Cloudflare Access applications the platform owns, and their policies.
+             * `id` is Cloudflare's app id. */
+            access: {
+                /** Every live app with its owner (`null`: no row), optionally narrowed
+                 * by exact `domain` and/or `name`. */
+                list: (filter = {}) => call('GET', `/v1/platform/access/apps${query(filter)}`),
+                /** Creates the app, or returns the one edge already made for that
+                 * domain and name. Rejects with `conflict` when a live app holds the
+                 * domain that nobody adopted (adopt it instead). */
+                create: (input) => call('POST', '/v1/platform/access/apps', input),
+                /** Deletes the app; returns the tombstone. Repeating it rejects with `not_found`. */
+                remove: (id) => call('DELETE', `/v1/platform/access/apps/${encodeURIComponent(id)}`),
+                /** The policies on an app the platform owns. */
+                listPolicies: (appId) => call('GET', `/v1/platform/access/apps/${encodeURIComponent(appId)}/policies`),
+                /** Adds a policy. The same name with the same content returns it as it
+                 * is (safe to repeat); the same name with other content rejects with `conflict`. */
+                createPolicy: (appId, input) => call('POST', `/v1/platform/access/apps/${encodeURIComponent(appId)}/policies`, input),
+                /** A service token's id by exact name; `token` is `null` when none has
+                 * it. Read-only: the secret is never returned. */
+                findServiceToken: (name) => call('GET', `/v1/platform/access/service-tokens?${new URLSearchParams({ name })}`),
+                /** Writes platform rows for the live apps named. Nothing is deleted or
+                 * recreated, and an app nobody names is left alone. */
+                adopt: (input) => call('POST', '/v1/platform/access/apps/adopt', input),
+            },
+            /** Cloudflare Workers scripts and routes the platform owns. A script's
+             * `id` is its name; a route's `id` is Cloudflare's route id. */
+            workers: {
+                /** Every live script with its owner (`null`: no row), optionally only the one named `name`. */
+                listScripts: (filter = {}) => call('GET', `/v1/platform/workers/scripts${filter.name === undefined ? '' : `?${new URLSearchParams({ name: filter.name })}`}`),
+                /** Uploads the script (base64, at most 10 MB), or redeploys the one edge
+                 * already owns (201 on the first upload, 200 after). Rejects with
+                 * `conflict` when a live script of that name exists that nobody adopted
+                 * (adopt it instead) or another upload of the name is in progress, and
+                 * with `invalid_request` when the script is not base64 or its sha256
+                 * differs from `artifactSha256`. */
+                uploadScript: (name, input) => call('PUT', `/v1/platform/workers/scripts/${encodeURIComponent(name)}`, input),
+                /** Deletes the script; returns the tombstone. Repeating it rejects with `not_found`. */
+                removeScript: (name) => call('DELETE', `/v1/platform/workers/scripts/${encodeURIComponent(name)}`),
+                /** Every live route in the zone with its owner (`null`: no row), optionally only one pattern. */
+                listRoutes: (filter) => call('GET', `/v1/platform/workers/routes?${new URLSearchParams(Object.entries(filter).filter((entry) => entry[1] !== undefined))}`),
+                /** Creates the route, or returns the one edge already made for that
+                 * zone, pattern and script. Rejects with `conflict` when a live route
+                 * holds the pattern that nobody adopted (adopt it instead). */
+                createRoute: (input) => call('POST', '/v1/platform/workers/routes', input),
+                /** Deletes the route in `zoneId`; returns the tombstone. Repeating it rejects with `not_found`. */
+                removeRoute: (zoneId, id) => call('DELETE', `/v1/platform/workers/routes/${encodeURIComponent(id)}?${new URLSearchParams({ zoneId })}`),
+                /** Writes platform rows for the scripts and routes named. Nothing is
+                 * deleted or recreated, and anything nobody names is left alone. */
+                adopt: (input) => call('POST', '/v1/platform/workers/adopt', input),
+            },
         },
         /** 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 })}`),

package/dist/types.d.ts

@@ -101,8 +101,9 @@ export interface OrgSettingsRequest {
  * 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';
+ * until the hold ends. `exists`: a tunnel of that name already exists at
+ * Cloudflare; adopt it instead. `upstream_rejected`: Cloudflare permanently refused; do not retry. */
+export type EdgeConflictReason = 'busy' | 'pending' | 'removing' | 'taken' | 'held' | 'exists' | 'upstream_rejected';
 export type RecordType = 'TXT' | 'MX' | 'CNAME' | 'A' | 'AAAA' | 'CAA';
 /** CAA's structured value, in Cloudflare's form. */
 export interface CaaData {
@@ -269,6 +270,8 @@ export interface CreatePlatformTunnelRequest {
 /** One ingress rule. Every rule but the last names a hostname; the last is the catch-all. */
 export interface TunnelIngressRule {
     hostname?: string;
+    /** A regex Cloudflare matches against the request path, to tell rules on one hostname apart. */
+    path?: string;
     service: string;
     originRequest?: Record<string, unknown>;
 }
@@ -299,3 +302,202 @@ export interface AdoptTunnelsResponse {
     /** Live tunnels no entry named. Reported, never touched. */
     unclaimed: PlatformTunnelView[];
 }
+/** An Access application seen with the platform credential. `id` is Cloudflare's
+ * app id, which every platform Access call takes. */
+export interface PlatformAccessAppView {
+    id: string;
+    name: string;
+    domain: string;
+    /** Who owns it: the platform, or `null` when no row exists (a live app
+     * nobody adopted: reported, never touched). */
+    owner: 'platform' | null;
+    /** The company the app serves; `'platform'` when none. `null` for an app with no row. */
+    organisationId: string | null;
+    state: 'pending' | 'active' | 'removing' | 'removed';
+}
+export interface ListPlatformAccessAppsRequest {
+    /** Only the app on exactly this domain. */
+    domain?: string;
+    /** Only the apps with exactly this name. */
+    name?: string;
+}
+export interface ListPlatformAccessAppsResponse {
+    apps: PlatformAccessAppView[];
+}
+/** Creates the app, or returns the one edge already made for that domain and name. */
+export interface CreatePlatformAccessAppRequest {
+    name: string;
+    /** A lower-case hostname, optionally with a leading `*.`. */
+    domain: string;
+    /** Only `self_hosted` is supported (the default). */
+    type?: 'self_hosted';
+    /** Like `30m` or `24h`. */
+    sessionDuration?: string;
+    autoRedirectToIdentity?: boolean;
+    /** The company the app serves. Omit for an app that serves none. */
+    organisationId?: string;
+}
+/** One Access rule, in Cloudflare's own shape: `{ email: { email } }`, `{ everyone: {} }`, `{ service_token: { token_id } }`. */
+export type AccessRule = Record<string, unknown>;
+export type AccessDecision = 'allow' | 'deny' | 'non_identity' | 'bypass';
+export interface PlatformAccessPolicyView {
+    id: string;
+    name: string;
+    decision: AccessDecision;
+    include: AccessRule[];
+    exclude?: AccessRule[];
+    require?: AccessRule[];
+}
+export interface ListPlatformAccessPoliciesResponse {
+    policies: PlatformAccessPolicyView[];
+}
+/** Adds a policy to an app the platform owns. At least one `include` rule is required. */
+export interface CreatePlatformAccessPolicyRequest {
+    name: string;
+    decision: AccessDecision;
+    include: AccessRule[];
+    exclude?: AccessRule[];
+    require?: AccessRule[];
+}
+/** A service token's id and name. Its secret is never returned. */
+export interface FindServiceTokenResponse {
+    token: {
+        id: string;
+        name: string;
+    } | null;
+}
+export interface AdoptAccessAppEntry {
+    name: string;
+    /** Narrows several apps of one name. */
+    domain?: string;
+    /** Cloudflare's id, when the caller recorded it: the match must carry it. */
+    id?: string;
+}
+export interface AdoptAccessAppsRequest {
+    apps: AdoptAccessAppEntry[];
+    /** The company the adopted apps serve. Omit for none. */
+    organisationId?: string;
+}
+export interface AdoptAccessAppsResponse {
+    adopted: PlatformAccessAppView[];
+    alreadyAdopted: PlatformAccessAppView[];
+    /** `taken`: a row for that domain exists. `unsupported_type`: the app has
+     * no domain (not self-hosted). */
+    skipped: Array<{
+        app: PlatformAccessAppView;
+        reason: 'taken' | 'unsupported_type';
+    }>;
+    /** Entries with no live app. Nothing is created for them. */
+    notFound: AdoptAccessAppEntry[];
+    /** Live apps no entry named. Reported, never touched. */
+    unclaimed: PlatformAccessAppView[];
+}
+/** A Workers script seen with the platform credential. `id` is the script's
+ * name, which every platform script call takes. */
+export interface PlatformWorkerScriptView {
+    id: string;
+    name: string;
+    /** Who owns it: the platform, or `null` when no row exists (a live script
+     * nobody adopted: reported, never touched). */
+    owner: 'platform' | null;
+    /** The company the script serves; `'platform'` when none. `null` for a script with no row. */
+    organisationId: string | null;
+    state: 'pending' | 'active' | 'removing' | 'removed';
+}
+export interface ListPlatformWorkerScriptsResponse {
+    scripts: PlatformWorkerScriptView[];
+}
+/** One rate limiting binding, Cloudflare's own shape. */
+export interface WorkerRateLimitBinding {
+    type: 'ratelimit';
+    name: string;
+    namespace_id: string;
+    simple: {
+        limit: number;
+        period: number;
+    };
+}
+/** Uploads (or redeploys) a script. Edge fetches nothing: the caller sends the
+ * script, edge checks its size and sha256, and sends it to Cloudflare. The body
+ * is never stored or returned. */
+export interface UploadPlatformWorkerScriptRequest {
+    /** The script (one ES module) as base64 text, at most 10 MB decoded. */
+    script: string;
+    /** The script's sha256, 64 hex characters. A script with another digest is refused with `invalid_request`. */
+    artifactSha256: string;
+    /** Like `2026-10-01`. */
+    compatibilityDate: string;
+    bindings?: WorkerRateLimitBinding[];
+    /** The company the script serves. Omit for a script that serves none. */
+    organisationId?: string;
+}
+/** A Workers route seen with the platform credential. `id` is Cloudflare's
+ * route id, which every platform route call takes. */
+export interface PlatformWorkerRouteView {
+    id: string;
+    zoneId: string;
+    pattern: string;
+    /** The script it runs, or `null` for the "no Worker" route. */
+    script: string | null;
+    /** Who owns it: the platform, or `null` when no row exists. */
+    owner: 'platform' | null;
+    /** The company the route serves; `'platform'` when none. `null` for a route with no row. */
+    organisationId: string | null;
+    state: 'pending' | 'active' | 'removing' | 'removed';
+}
+export interface ListPlatformWorkerRoutesRequest {
+    zoneId: string;
+    /** Only the route on exactly this pattern. */
+    pattern?: string;
+}
+export interface ListPlatformWorkerRoutesResponse {
+    routes: PlatformWorkerRouteView[];
+}
+/** Creates the route, or returns the one edge already made for that zone,
+ * pattern and script. With no `script` it makes Cloudflare's "no Worker"
+ * route, which turns Workers off for the pattern. */
+export interface CreatePlatformWorkerRouteRequest {
+    zoneId: string;
+    pattern: string;
+    script?: string;
+    /** The company the route serves. Omit for a route that serves none. */
+    organisationId?: string;
+}
+export interface AdoptWorkerScriptEntry {
+    name: string;
+}
+export interface AdoptWorkerRouteEntry {
+    zoneId: string;
+    pattern: string;
+    /** Cloudflare's id, when the caller recorded it: the match must carry it. */
+    id?: string;
+}
+/** Name at least one script or route. */
+export interface AdoptWorkersRequest {
+    scripts?: AdoptWorkerScriptEntry[];
+    routes?: AdoptWorkerRouteEntry[];
+    /** The company the adopted items serve. Omit for none. */
+    organisationId?: string;
+}
+export interface AdoptWorkersResponse {
+    scripts: {
+        adopted: PlatformWorkerScriptView[];
+        alreadyAdopted: PlatformWorkerScriptView[];
+        /** Entries with no live script. Nothing is created for them. */
+        notFound: AdoptWorkerScriptEntry[];
+        /** Live scripts no entry named. Reported, never touched. */
+        unclaimed: PlatformWorkerScriptView[];
+    };
+    routes: {
+        adopted: PlatformWorkerRouteView[];
+        alreadyAdopted: PlatformWorkerRouteView[];
+        /** `taken`: a row for that zone and pattern exists. */
+        skipped: Array<{
+            route: PlatformWorkerRouteView;
+            reason: 'taken';
+        }>;
+        notFound: AdoptWorkerRouteEntry[];
+        /** Live routes in the named zones that no entry named. Reported, never touched. */
+        unclaimed: PlatformWorkerRouteView[];
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/edge",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "type": "module",
   "license": "MIT",
   "description": "Public client SDK and API types for the edge service.",