@wtfalch/edge 0.9.0 → 0.11.0

package/dist/client.d.ts

@@ -1,10 +1,19 @@
 import { type ClientOptions } from './transport.js';
-import type { AdoptAccessAppsRequest, AdoptAccessAppsResponse, AdoptRateLimitRulesRequest, AdoptRateLimitRulesResponse, AdoptRecordsRequest, AdoptRecordsResponse, AdoptTunnelsRequest, AdoptTunnelsResponse, AdoptWorkersRequest, AdoptWorkersResponse, AdoptZonesRequest, AdoptZonesResponse, AvailableResponse, ClaimNameRequest, CreatePlatformAccessAppRequest, CreatePlatformAccessPolicyRequest, CreatePlatformRateLimitRuleRequest, CreatePlatformRecordRequest, CreatePlatformTunnelRequest, CreatePlatformWorkerRouteRequest, CreatePlatformZoneRequest, FindServiceTokenResponse, ListClaimsResponse, ListPlatformAccessAppsRequest, ListPlatformAccessAppsResponse, ListPlatformAccessPoliciesResponse, ListPlatformRateLimitRulesRequest, ListPlatformRateLimitRulesResponse, ListPlatformRecordsRequest, ListPlatformRecordsResponse, ListPlatformTunnelsResponse, ListPlatformWorkerRoutesRequest, ListPlatformWorkerRoutesResponse, ListPlatformWorkerScriptsResponse, ListPlatformZonesRequest, ListPlatformZonesResponse, ListRecordsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OrgSettingsRequest, PlatformAccessAppView, PlatformAccessPolicyView, PlatformRateLimitRuleView, PlatformRecordView, PlatformTunnelView, PlatformWorkerRouteView, PlatformWorkerScriptView, PlatformZoneView, PutPlatformTunnelConfigRequest, RecordInput, RecordPatch, RecordView, TokenResponse, UpdatePlatformRecordRequest, UploadPlatformWorkerScriptRequest } from './types.js';
+import type { AccessProviderView, AccessReadinessResponse, AdoptAccessAppsRequest, AdoptAccessAppsResponse, AdoptRateLimitRulesRequest, AdoptRateLimitRulesResponse, AdoptRecordsRequest, AdoptRecordsResponse, AdoptTunnelsRequest, AdoptTunnelsResponse, AdoptWorkersRequest, AdoptWorkersResponse, AdoptZonesRequest, AdoptZonesResponse, AvailableResponse, ClaimNameRequest, CreatePlatformAccessAppRequest, CreatePlatformAccessPolicyRequest, CreatePlatformGateRequest, CreatePlatformRateLimitRuleRequest, CreatePlatformRecordRequest, CreatePlatformTunnelRequest, CreatePlatformWorkerRouteRequest, CreatePlatformZoneRequest, EnsureAccessProviderRequest, FindServiceTokenResponse, ListClaimsResponse, ListGatesResponse, ListPlatformAccessAppsRequest, ListPlatformAccessAppsResponse, ListPlatformAccessPoliciesResponse, ListPlatformRateLimitRulesRequest, ListPlatformRateLimitRulesResponse, ListPlatformRecordsRequest, ListPlatformRecordsResponse, ListPlatformTunnelsResponse, ListPlatformWorkerRoutesRequest, ListPlatformWorkerRoutesResponse, ListPlatformWorkerScriptsResponse, ListPlatformZonesRequest, ListPlatformZonesResponse, ListRecordsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OrgSettingsRequest, PlatformAccessAppView, PlatformAccessPolicyView, PlatformGateView, PlatformRateLimitRuleView, PlatformRecordView, PlatformTunnelView, PlatformWorkerRouteView, PlatformWorkerScriptView, PlatformZoneView, PutPlatformTunnelConfigRequest, RecordInput, RecordPatch, RecordView, ReplacePlatformGateHostnamesRequest, SetGatePeopleResponse, SetPlatformWorkerSchedulesRequest, SetPlatformWorkerSchedulesResponse, SetPlatformWorkerSecretsRequest, SetPlatformWorkerSecretsResponse, 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
  * refused by the service for any credential but the platform's own. */
 export declare function createEdgeClient(options: ClientOptions): {
+    /** The org's gates. Needs `gates:read` (`gates:edit` for `setPeople`). */
+    gates: {
+        /** The org's gates, each with the people who pass it now. */
+        list: () => Promise<ListGatesResponse>;
+        /** Replaces the people who pass a gate with `emails` (1 to 1000), then when
+         * the list drops anyone, ends every session on the gate. `revoked` is false
+         * when that did not happen; the list is replaced regardless. */
+        setPeople: (id: string, emails: string[]) => Promise<SetGatePeopleResponse>;
+    };
     /** 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
@@ -84,6 +93,19 @@ export declare function createEdgeClient(options: ClientOptions): {
             /** 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>;
+            /** Resolves when the Cloudflare token holds every Access right gates
+             * need. Rejects with `not_configured`, naming each right it lacks. */
+            readiness: () => Promise<AccessReadinessResponse>;
+            /** Creates the OIDC provider, or updates the one of that name; returns
+             * its id. The client secret is never returned. */
+            ensureProvider: (input: EnsureAccessProviderRequest) => Promise<AccessProviderView>;
+            /** Makes a company's gate. Rejects with `conflict` when the company
+             * already has a gate of that key. */
+            createGate: (input: CreatePlatformGateRequest) => Promise<PlatformGateView>;
+            /** Replaces the hostnames a gate covers. */
+            replaceGateHostnames: (id: string, input: ReplacePlatformGateHostnamesRequest) => Promise<PlatformGateView>;
+            /** Deletes a gate with its application, policy and group. */
+            deleteGate: (id: string) => Promise<PlatformGateView>;
         };
         /** Cloudflare rate limiting rules the platform owns. A zone's rules share
          * one ruleset, so each rule is owned on its own; a rule's `id` is
@@ -134,7 +156,16 @@ export declare function createEdgeClient(options: ClientOptions): {
              * 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`. */
+            /** Sets the script's cron triggers to exactly `crons` (an empty list
+             * clears them). Safe to repeat. Rejects with `not_found` when edge does
+             * not own an active script of that name, and `invalid_request` for a bad expression. */
+            setSchedules: (name: string, input: SetPlatformWorkerSchedulesRequest) => Promise<SetPlatformWorkerSchedulesResponse>;
+            /** Sets secret_text bindings on the script. Write-only: no response, audit
+             * row or error carries a value. A secret whose `version` equals the stored
+             * one is skipped (`changed: false`); a new version sets the value again.
+             * Survives `uploadScript` redeploys. Deleting the script removes them. */
+            setSecrets: (name: string, input: SetPlatformWorkerSecretsRequest) => Promise<SetPlatformWorkerSecretsResponse>;
+            /** Deletes the script, its cron triggers and the KV namespaces edge created for it; 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>;

package/dist/client.js

@@ -10,6 +10,17 @@ function query(values) {
 export function createEdgeClient(options) {
     const call = createTransport(options);
     return {
+        /** The org's gates. Needs `gates:read` (`gates:edit` for `setPeople`). */
+        gates: {
+            /** The org's gates, each with the people who pass it now. */
+            list: () => call('GET', '/v1/gates'),
+            /** Replaces the people who pass a gate with `emails` (1 to 1000), then when
+             * the list drops anyone, ends every session on the gate. `revoked` is false
+             * when that did not happen; the list is replaced regardless. */
+            setPeople: (id, emails) => call('PUT', `/v1/gates/${encodeURIComponent(id)}/people`, {
+                emails,
+            }),
+        },
         /** 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
@@ -87,6 +98,19 @@ export function createEdgeClient(options) {
                 /** 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),
+                /** Resolves when the Cloudflare token holds every Access right gates
+                 * need. Rejects with `not_configured`, naming each right it lacks. */
+                readiness: () => call('GET', '/v1/platform/access/readiness'),
+                /** Creates the OIDC provider, or updates the one of that name; returns
+                 * its id. The client secret is never returned. */
+                ensureProvider: (input) => call('PUT', '/v1/platform/access/identity-providers', input),
+                /** Makes a company's gate. Rejects with `conflict` when the company
+                 * already has a gate of that key. */
+                createGate: (input) => call('POST', '/v1/platform/access/gates', input),
+                /** Replaces the hostnames a gate covers. */
+                replaceGateHostnames: (id, input) => call('PUT', `/v1/platform/access/gates/${encodeURIComponent(id)}/hostnames`, input),
+                /** Deletes a gate with its application, policy and group. */
+                deleteGate: (id) => call('DELETE', `/v1/platform/access/gates/${encodeURIComponent(id)}`),
             },
             /** Cloudflare rate limiting rules the platform owns. A zone's rules share
              * one ruleset, so each rule is owned on its own; a rule's `id` is
@@ -135,7 +159,16 @@ export function createEdgeClient(options) {
                  * 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`. */
+                /** Sets the script's cron triggers to exactly `crons` (an empty list
+                 * clears them). Safe to repeat. Rejects with `not_found` when edge does
+                 * not own an active script of that name, and `invalid_request` for a bad expression. */
+                setSchedules: (name, input) => call('PUT', `/v1/platform/workers/scripts/${encodeURIComponent(name)}/schedules`, input),
+                /** Sets secret_text bindings on the script. Write-only: no response, audit
+                 * row or error carries a value. A secret whose `version` equals the stored
+                 * one is skipped (`changed: false`); a new version sets the value again.
+                 * Survives `uploadScript` redeploys. Deleting the script removes them. */
+                setSecrets: (name, input) => call('PUT', `/v1/platform/workers/scripts/${encodeURIComponent(name)}/secrets`, input),
+                /** Deletes the script, its cron triggers and the KV namespaces edge created for it; 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))}`),

package/dist/types.d.ts

@@ -359,6 +359,83 @@ export interface CreatePlatformAccessPolicyRequest {
     exclude?: AccessRule[];
     require?: AccessRule[];
 }
+/** The sign-in provider every gate requires: a generic OIDC provider, found by `name`. */
+export interface EnsureAccessProviderRequest {
+    name: string;
+    clientId: string;
+    /** Sent to Cloudflare and never returned. */
+    clientSecret: string;
+    authUrl: string;
+    tokenUrl: string;
+    certsUrl: string;
+    scopes: string[];
+    claims: string[];
+}
+export interface AccessProviderView {
+    /** Cloudflare's id for the provider: what a gate takes as `providerId`. */
+    id: string;
+    name: string;
+}
+/** Whether the Cloudflare token holds every Access right gates need. A token that lacks one, or an organisation with no team address, rejects with `not_configured`, naming each missing right. */
+export interface AccessReadinessResponse {
+    ready: true;
+    /** The Access organisation's team address, for example `team.cloudflareaccess.com`. */
+    authDomain: string;
+}
+/** Makes a company's gate: an application over `hostnames`, a group of `emails`, and a policy that requires the provider and one OIDC claim. */
+export interface CreatePlatformGateRequest {
+    organisationId: string;
+    /** A lower-case DNS label, unique in the company. */
+    key: string;
+    /** The key of the app entry that declared the gate: a lower-case DNS label. */
+    entry: string;
+    /** The hostnames the gate covers, a leading `*.` allowed. */
+    hostnames: string[];
+    /** The provider's id from `ensureProvider`. */
+    providerId: string;
+    claimName: string;
+    claimValue: string;
+    /** The first list of people: 1 to 1000 addresses. */
+    emails: string[];
+}
+export interface ReplacePlatformGateHostnamesRequest {
+    hostnames: string[];
+}
+/** A company's gate. `id` is edge's gate id, which the change and delete calls take. */
+export interface PlatformGateView {
+    id: string;
+    organisationId: string;
+    key: string;
+    /** The key of the app entry that declared the gate. */
+    entry: string;
+    hostnames: string[];
+    providerId: string;
+    applicationId: string;
+    groupId: string;
+}
+/** A gate as its company sees it. */
+export interface GateView {
+    /** Edge's gate id: what `setPeople` takes. */
+    id: string;
+    key: string;
+    /** The key of the app entry that declared the gate. */
+    entry: string;
+    hostnames: string[];
+    /** The addresses that pass the gate, lower-case. */
+    people: string[];
+}
+export interface ListGatesResponse {
+    gates: GateView[];
+}
+/** The whole list of people for a gate: 1 to 1000 addresses. Duplicates collapse and case is ignored. */
+export interface SetGatePeopleRequest {
+    emails: string[];
+}
+/** The gate with its new people. The list is replaced even when a revoke fails. */
+export interface SetGatePeopleResponse extends GateView {
+    /** Whether this call ended every session on the gate. False when nobody was dropped, or when Cloudflare refused: the next update tries again. */
+    revoked: boolean;
+}
 /** A service token's id and name. Its secret is never returned. */
 export interface FindServiceTokenResponse {
     token: {
@@ -417,6 +494,23 @@ export interface WorkerRateLimitBinding {
         period: number;
     };
 }
+/** A KV namespace bound to the script as `name`. Edge finds the namespace by
+ * `title`, reuses it when it exists and creates it when it does not. A
+ * namespace edge created is deleted with the script; one it only reused is kept. */
+export interface WorkerKvBinding {
+    type: 'kv_namespace';
+    name: string;
+    /** 1 to 100 letters, digits, `.`, `_` or `-`. Unique in the account; one script holds it. */
+    title: string;
+}
+/** An environment binding whose value is not secret (at most 5120 characters). */
+export interface WorkerPlainTextBinding {
+    type: 'plain_text';
+    name: string;
+    text: string;
+}
+/** Everything `uploadScript` accepts in `bindings`. Secrets are not here: see `setSecrets`. */
+export type WorkerBinding = WorkerRateLimitBinding | WorkerKvBinding | WorkerPlainTextBinding;
 /** 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. */
@@ -427,10 +521,48 @@ export interface UploadPlatformWorkerScriptRequest {
     artifactSha256: string;
     /** Like `2026-10-01`. */
     compatibilityDate: string;
-    bindings?: WorkerRateLimitBinding[];
+    /** The script's bindings, all of them: a redeploy replaces the list. Secrets set by `setSecrets` survive a redeploy. */
+    bindings?: WorkerBinding[];
     /** The company the script serves. Omit for a script that serves none. */
     organisationId?: string;
 }
+/** Replaces the script's cron triggers with exactly `crons`. An empty list clears them. */
+export interface SetPlatformWorkerSchedulesRequest {
+    /** Up to 50 expressions of five fields, like `* * * * *`. Duplicates collapse. */
+    crons: string[];
+}
+export interface SetPlatformWorkerSchedulesResponse {
+    name: string;
+    /** The list now set, de-duplicated and sorted. */
+    crons: string[];
+}
+/** One secret_text binding. `value` goes to Cloudflare and is never stored,
+ * returned, audited or logged. `version` is a label you choose and keep, such
+ * as a rotation counter or a fingerprint of a high-entropy secret. Edge stores
+ * it beside the name: the same version is skipped, a new one sets `value` again.
+ * Do not use an unsalted hash of a guessable value. */
+export interface PlatformWorkerSecretInput {
+    /** The binding name, like `UPTIME_TOKEN`. */
+    name: string;
+    /** 1 to 5120 bytes. */
+    value: string;
+    /** 1 to 128 printable characters. */
+    version: string;
+}
+export interface SetPlatformWorkerSecretsRequest {
+    /** 1 to 50 secrets, names unique. */
+    secrets: PlatformWorkerSecretInput[];
+}
+export interface PlatformWorkerSecretView {
+    name: string;
+    version: string;
+    /** False when the stored version equalled the one sent, so nothing was sent to Cloudflare. */
+    changed: boolean;
+}
+export interface SetPlatformWorkerSecretsResponse {
+    name: string;
+    secrets: PlatformWorkerSecretView[];
+}
 /** A Workers route seen with the platform credential. `id` is Cloudflare's
  * route id, which every platform route call takes. */
 export interface PlatformWorkerRouteView {

package/package.json

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