@wtfalch/edge 0.3.0 → 0.4.0

package/README.md

@@ -33,6 +33,21 @@ 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,
+});
+```
+
 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, AvailableResponse, ClaimNameRequest, CreatePlatformRecordRequest, ListClaimsResponse, ListPlatformRecordsRequest, ListPlatformRecordsResponse, ListRecordsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OrgSettingsRequest, PlatformRecordView, 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,25 @@ 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>;
+        };
+    };
     /** 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,25 @@ 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),
+            },
+        },
         /** 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,89 @@ 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[];
+}

package/package.json

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