@wtfalch/edge 0.3.0 → 0.5.0

package/README.md

@@ -33,6 +33,34 @@ await edge.records.update(www.id, { ttl: 300 });
 await edge.records.remove(www.id);
 ```
 
+```ts
+// With the platform credential only: DNS in any zone
+await edge.platform.dns.adopt({
+  zone: 'acme.com',
+  records: [{ name: 'acme.com', type: 'MX' }],
+});
+await edge.platform.dns.create({
+  zone: 'acme.com',
+  name: 'app.acme.com',
+  type: 'CNAME',
+  content: 'tun.cfargotunnel.com',
+  proxied: true,
+});
+```
+
+```ts
+// With the platform credential only: a tunnel with many hostnames
+const tunnel = await edge.platform.tunnels.create({ name: 'acme-tunnel' });
+await edge.platform.tunnels.putConfig(tunnel.id, {
+  ingress: [
+    { hostname: 'app.acme.com', service: 'http://proxy:80' },
+    { hostname: 'cms.acme.com', service: 'http://proxy:80' },
+    { service: 'http_status:404' },
+  ],
+});
+const { token } = await edge.platform.tunnels.token(tunnel.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

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type ClientOptions } from './transport.js';
-import type { AvailableResponse, ClaimNameRequest, ListClaimsResponse, ListRecordsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OrgSettingsRequest, RecordInput, RecordPatch, RecordView, TokenResponse } from './types.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';
 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
@@ -21,6 +21,47 @@ export declare function createEdgeClient(options: ClientOptions): {
         /** Returns the tombstone (`state: 'removed'`); repeating it is safe. */
         remove: (id: string) => Promise<RecordView>;
     };
+    /** Platform credential only: DNS in any zone. An entry key is refused on
+     * every call. Each record is a platform-owned row; `id` is Cloudflare's. */
+    platform: {
+        dns: {
+            /** Live records in the zone, each with its owner (`null`: no row). */
+            list: (input: ListPlatformRecordsRequest) => Promise<ListPlatformRecordsResponse>;
+            /** Writes a record the company cannot: mail-authentication TXT, a
+             * platform label, the apex, a proxied record. Safe to repeat. */
+            create: (input: CreatePlatformRecordRequest) => Promise<PlatformRecordView>;
+            /** Changes an adopted or created record. Rejects with `not_found` for a
+             * live record nobody adopted, and `forbidden` for a company's own. */
+            update: (zone: string, id: string, patch: UpdatePlatformRecordRequest) => Promise<PlatformRecordView>;
+            /** Returns the tombstone (`state: 'removed'`); repeating it is safe. */
+            remove: (zone: string, id: string) => Promise<PlatformRecordView>;
+            /** Writes platform-owned rows for the live records named. Nothing is
+             * deleted or recreated, and a record nobody names is left alone. */
+            adopt: (input: AdoptRecordsRequest) => Promise<AdoptRecordsResponse>;
+        };
+        /** Tunnels the platform owns, one per company or service, each with
+         * many hostnames in its ingress. A name claim's own tunnel is never
+         * reachable here. `id` is Cloudflare's tunnel id. */
+        tunnels: {
+            /** Every live tunnel with its owner, optionally only the one named `name`. */
+            list: (filter?: {
+                name?: string;
+            }) => Promise<ListPlatformTunnelsResponse>;
+            /** Creates the tunnel, or returns the one edge already made under that
+             * name. Rejects with `conflict` when a live tunnel of that name exists
+             * that nobody adopted (adopt it instead). */
+            create: (input: CreatePlatformTunnelRequest) => Promise<PlatformTunnelView>;
+            /** Replaces the tunnel's whole ingress. */
+            putConfig: (id: string, input: PutPlatformTunnelConfigRequest) => Promise<PlatformTunnelView>;
+            /** The connector token: a secret. Hand it to the connector and nowhere else. */
+            token: (id: string) => Promise<TokenResponse>;
+            /** Drops the connections and deletes the tunnel; returns the tombstone. */
+            remove: (id: string) => Promise<PlatformTunnelView>;
+            /** Writes platform rows for the live tunnels named. Nothing is deleted
+             * or recreated, and a tunnel nobody names is left alone. */
+            adopt: (input: AdoptTunnelsRequest) => Promise<AdoptTunnelsResponse>;
+        };
+    };
     /** 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

package/dist/client.js

@@ -22,6 +22,45 @@ export function createEdgeClient(options) {
             /** Returns the tombstone (`state: 'removed'`); repeating it is safe. */
             remove: (id) => call('DELETE', `/v1/records/${encodeURIComponent(id)}`),
         },
+        /** Platform credential only: DNS in any zone. An entry key is refused on
+         * every call. Each record is a platform-owned row; `id` is Cloudflare's. */
+        platform: {
+            dns: {
+                /** Live records in the zone, each with its owner (`null`: no row). */
+                list: (input) => call('GET', `/v1/platform/dns/records?${new URLSearchParams(Object.entries(input).filter((entry) => !!entry[1]))}`),
+                /** Writes a record the company cannot: mail-authentication TXT, a
+                 * platform label, the apex, a proxied record. Safe to repeat. */
+                create: (input) => call('POST', '/v1/platform/dns/records', input),
+                /** Changes an adopted or created record. Rejects with `not_found` for a
+                 * live record nobody adopted, and `forbidden` for a company's own. */
+                update: (zone, id, patch) => call('PATCH', `/v1/platform/dns/records/${encodeURIComponent(id)}?${new URLSearchParams({ zone })}`, patch),
+                /** Returns the tombstone (`state: 'removed'`); repeating it is safe. */
+                remove: (zone, id) => call('DELETE', `/v1/platform/dns/records/${encodeURIComponent(id)}?${new URLSearchParams({ zone })}`),
+                /** Writes platform-owned rows for the live records named. Nothing is
+                 * deleted or recreated, and a record nobody names is left alone. */
+                adopt: (input) => call('POST', '/v1/platform/dns/adopt', input),
+            },
+            /** Tunnels the platform owns, one per company or service, each with
+             * many hostnames in its ingress. A name claim's own tunnel is never
+             * reachable here. `id` is Cloudflare's tunnel id. */
+            tunnels: {
+                /** Every live tunnel with its owner, optionally only the one named `name`. */
+                list: (filter = {}) => call('GET', `/v1/platform/tunnels${filter.name === undefined ? '' : `?${new URLSearchParams({ name: filter.name })}`}`),
+                /** Creates the tunnel, or returns the one edge already made under that
+                 * name. Rejects with `conflict` when a live tunnel of that name exists
+                 * that nobody adopted (adopt it instead). */
+                create: (input) => call('POST', '/v1/platform/tunnels', input),
+                /** Replaces the tunnel's whole ingress. */
+                putConfig: (id, input) => call('PUT', `/v1/platform/tunnels/${encodeURIComponent(id)}/config`, input),
+                /** The connector token: a secret. Hand it to the connector and nowhere else. */
+                token: (id) => call('GET', `/v1/platform/tunnels/${encodeURIComponent(id)}/token`),
+                /** Drops the connections and deletes the tunnel; returns the tombstone. */
+                remove: (id) => call('DELETE', `/v1/platform/tunnels/${encodeURIComponent(id)}`),
+                /** Writes platform rows for the live tunnels named. Nothing is deleted
+                 * or recreated, and a tunnel nobody names is left alone. */
+                adopt: (input) => call('POST', '/v1/platform/tunnels/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 })}`),
         /** Creates the tunnel, routes `name` to `127.0.0.1:<port>` with a 404

package/dist/types.d.ts

@@ -157,3 +157,145 @@ export interface ListRecordsResponse {
  * 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'>;
+/** A DNS record in any zone, seen with the platform credential. `id` is
+ * Cloudflare's record id, which every platform call takes. */
+export interface PlatformRecordView {
+    id: string;
+    /** The full hostname. */
+    name: string;
+    type: string;
+    content: string;
+    ttl: number;
+    /** MX only; null otherwise. */
+    priority: number | null;
+    proxied: boolean;
+    /** Who owns it: the platform, an organisation, or `null` when no row exists
+     * (a live record nobody adopted: reported, never touched). */
+    owner: 'platform' | 'organisation' | null;
+    /** The company the row is for; `platform` for a row that belongs to none. */
+    organisationId: string | null;
+    state: 'pending' | 'active' | 'removing' | 'removed';
+}
+export interface ListPlatformRecordsRequest {
+    /** The zone's own domain, such as `acme.com`. */
+    zone: string;
+    /** A full hostname. */
+    name?: string;
+    type?: RecordType;
+}
+export interface ListPlatformRecordsResponse {
+    records: PlatformRecordView[];
+}
+/** Writes a platform-owned record: any label (including the apex and a name
+ * of several labels), mail-authentication TXT, and `proxied`. */
+export interface CreatePlatformRecordRequest {
+    zone: string;
+    /** The full hostname, inside the zone. */
+    name: 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. */
+    priority?: number;
+    /** A, AAAA and CNAME only. */
+    proxied?: boolean;
+    /** The company the record is for. Omit for a record that belongs to none. */
+    organisationId?: string;
+}
+/** The name and type never change: remove the record and create another. */
+export interface UpdatePlatformRecordRequest {
+    content?: string;
+    data?: CaaData;
+    ttl?: number;
+    priority?: number;
+    proxied?: boolean;
+}
+export interface AdoptRecordEntry {
+    /** The full hostname. */
+    name: string;
+    type: RecordType;
+    /** The Cloudflare id the caller recorded: the live record must carry it. */
+    id?: string;
+    /** Narrows several records of one type at one name. */
+    content?: string;
+}
+/** Adopts live records as platform-owned rows. Nothing is changed at Cloudflare. */
+export interface AdoptRecordsRequest {
+    zone: string;
+    records: AdoptRecordEntry[];
+    organisationId?: string;
+}
+export interface AdoptRecordsResponse {
+    adopted: PlatformRecordView[];
+    alreadyAdopted: PlatformRecordView[];
+    /** `organisation`: a company already owns it. `unsupported_type`: not a
+     * type edge holds. `taken`: an identical row exists. */
+    skipped: Array<{
+        record: PlatformRecordView;
+        reason: 'organisation' | 'unsupported_type' | 'taken';
+    }>;
+    /** Entries with no live record. Nothing is created for them. */
+    notFound: AdoptRecordEntry[];
+    /** Live records no entry named. Reported, never touched. */
+    unclaimed: PlatformRecordView[];
+}
+/** A tunnel seen with the platform credential. `id` is Cloudflare's tunnel id,
+ * which every platform tunnel call takes. */
+export interface PlatformTunnelView {
+    id: string;
+    name: string;
+    /** Who owns it: the platform, a name claim (an organisation's own: never
+     * touched here), or `null` when no row exists (a live tunnel nobody
+     * adopted: reported, never touched). */
+    owner: 'platform' | 'organisation' | null;
+    /** The company the tunnel serves; `'platform'` when none. `null` for a tunnel with no row. */
+    organisationId: string | null;
+    state: 'pending' | 'active' | 'removing' | 'removed';
+}
+export interface ListPlatformTunnelsResponse {
+    tunnels: PlatformTunnelView[];
+}
+/** Creates the named tunnel, or returns the one edge already made for it. */
+export interface CreatePlatformTunnelRequest {
+    /** Lower-case letters, digits, dots, dashes and underscores; not `names-…`. */
+    name: string;
+    /** The company the tunnel serves. Omit for a tunnel that serves none. */
+    organisationId?: string;
+}
+/** One ingress rule. Every rule but the last names a hostname; the last is the catch-all. */
+export interface TunnelIngressRule {
+    hostname?: string;
+    service: string;
+    originRequest?: Record<string, unknown>;
+}
+/** Replaces the tunnel's whole ingress (at most 100 rules). */
+export interface PutPlatformTunnelConfigRequest {
+    ingress: TunnelIngressRule[];
+}
+export interface AdoptTunnelEntry {
+    name: string;
+    /** Cloudflare's id, when the caller recorded it: the match must carry it. */
+    id?: string;
+}
+export interface AdoptTunnelsRequest {
+    tunnels: AdoptTunnelEntry[];
+    /** The company the adopted tunnels serve. Omit for none. */
+    organisationId?: string;
+}
+export interface AdoptTunnelsResponse {
+    adopted: PlatformTunnelView[];
+    alreadyAdopted: PlatformTunnelView[];
+    /** `organisation`: a name claim's tunnel. `taken`: a row with that name exists. */
+    skipped: Array<{
+        tunnel: PlatformTunnelView;
+        reason: 'organisation' | 'taken';
+    }>;
+    /** Entries with no live tunnel. Nothing is created for them. */
+    notFound: AdoptTunnelEntry[];
+    /** Live tunnels no entry named. Reported, never touched. */
+    unclaimed: PlatformTunnelView[];
+}

package/package.json

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