@wtfalch/edge 0.4.0 → 0.5.1

package/README.md

@@ -48,6 +48,19 @@ await edge.platform.dns.create({
 });
 ```
 
+```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 { AdoptRecordsRequest, AdoptRecordsResponse, AvailableResponse, ClaimNameRequest, CreatePlatformRecordRequest, ListClaimsResponse, ListPlatformRecordsRequest, ListPlatformRecordsResponse, ListRecordsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OrgSettingsRequest, PlatformRecordView, RecordInput, RecordPatch, RecordView, TokenResponse, UpdatePlatformRecordRequest } 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
@@ -39,6 +39,28 @@ export declare function createEdgeClient(options: ClientOptions): {
              * 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>;

package/dist/client.js

@@ -40,6 +40,26 @@ export function createEdgeClient(options) {
                  * 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 })}`),

package/dist/types.d.ts

@@ -243,3 +243,59 @@ export interface AdoptRecordsResponse {
     /** 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.4.0",
+  "version": "0.5.1",
   "type": "module",
   "license": "MIT",
   "description": "Public client SDK and API types for the edge service.",