@wtfalch/edge 0.2.0 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@ browser with Fetch support. The client has no runtime package dependencies.
 
 ## Status
 
-Published: no.
+Published: yes, v0.3.0, 2026-10-06.
 
 ```sh
 npm install @wtfalch/edge
@@ -25,12 +25,35 @@ if ((await edge.available('alice')).available) {
 }
 ```
 
+```ts
+// DNS records under the org's domain (`records:read`, `records:edit`)
+const { records } = await edge.records.list();
+const www = await edge.records.create({ label: 'www', type: 'A', content: '203.0.113.7' });
+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
 keeps it claimed; `remove` deletes the tunnel and record. `setReservedLabels`,
 `mintKey` and `revokeKey` need the platform credential and are refused for an
-entry key. A `remove` that already happened succeeds again, so a lost response is safe to retry. `rate_limited` errors carry `retryAfterSeconds`; a `conflict` with `reason: 'upstream_rejected'` means Cloudflare permanently refused, so do not retry it. API failures reject with `EdgeApiError`, which carries `status` and
+entry key. A `remove` that already happened succeeds again, so a lost response is safe to retry. `rate_limited` errors carry `retryAfterSeconds`; a `conflict` with `reason: 'upstream_rejected'` means Cloudflare permanently refused, so do not retry it. `records.list()` also shows the zone's other records as `owner: 'platform'`, `locked: true`; they are never changed through edge. `records.create` takes `label` (`@` for the apex, TXT only), `type` (TXT, MX, CNAME, A, AAAA, CAA) and `content`, or `data` for CAA. `records.update` changes `content`, `data`, `ttl` or `priority`; to change a label or type, remove the record and create another. A records `conflict` carries a `reason` of `busy`, `pending`, `removing`, `taken` or `upstream_rejected` (`RecordConflictReason`); a record the platform owns answers `forbidden`, and the org's records cap answers `over_budget`. API failures reject with `EdgeApiError`, which carries `status` and
 a typed `code` (see `EdgeError`); the SDK never throws a bare `Error` for a
 service failure.
 

package/dist/client.d.ts

@@ -1,10 +1,45 @@
 import { type ClientOptions } from './transport.js';
-import type { AvailableResponse, ClaimNameRequest, ListClaimsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OrgSettingsRequest, 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
  * refused by the service for any credential but the platform's own. */
 export declare function createEdgeClient(options: ClientOptions): {
+    /** 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
+         * locked platform record. */
+        list: () => Promise<ListRecordsResponse>;
+        /** Rejects with `not_found` when there is no such record. */
+        get: (id: string) => Promise<RecordView>;
+        /** Rejects with `conflict` (see `RecordConflictReason`) when the record
+         * exists or clashes, `forbidden` for a platform-owned label, and
+         * `over_budget` at the org's records cap. */
+        create: (input: RecordInput) => Promise<RecordView>;
+        /** Changes content, ttl or priority of the org's own record. */
+        update: (id: string, patch: RecordPatch) => Promise<RecordView>;
+        /** 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

@@ -6,6 +6,41 @@ export { EdgeApiError } from './transport.js';
 export function createEdgeClient(options) {
     const call = createTransport(options);
     return {
+        /** 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
+             * locked platform record. */
+            list: () => call('GET', '/v1/records'),
+            /** Rejects with `not_found` when there is no such record. */
+            get: (id) => call('GET', `/v1/records/${encodeURIComponent(id)}`),
+            /** Rejects with `conflict` (see `RecordConflictReason`) when the record
+             * exists or clashes, `forbidden` for a platform-owned label, and
+             * `over_budget` at the org's records cap. */
+            create: (input) => call('POST', '/v1/records', input),
+            /** Changes content, ttl or priority of the org's own record. */
+            update: (id, patch) => call('PATCH', `/v1/records/${encodeURIComponent(id)}`, patch),
+            /** 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

@@ -90,6 +90,8 @@ export interface OrgSettingsRequest {
     organisationId: string;
     /** Most live claims (pending, active, closed) this org may hold. */
     maxClaims?: number | null;
+    /** Most live DNS records this org may hold. */
+    maxRecords?: number | null;
     /** Rate bucket: calls allowed in a burst. */
     rateBurst?: number | null;
     /** Rate bucket: calls refilled per second. */
@@ -101,3 +103,143 @@ export interface OrgSettingsRequest {
  * 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';
+export type RecordType = 'TXT' | 'MX' | 'CNAME' | 'A' | 'AAAA' | 'CAA';
+/** CAA's structured value, in Cloudflare's form. */
+export interface CaaData {
+    flags: number;
+    tag: string;
+    value: string;
+}
+/** A DNS record in the organisation's zone. The org's own records have
+ * `owner: 'organisation'`; every other live record in the zone is shown as
+ * `owner: 'platform'` with `locked: true` and is never changed through edge. */
+export interface RecordView {
+    /** The row id for the org's own record; Cloudflare's id for a platform one. */
+    id: string;
+    /** The label under the org's domain; the apex is `@`. */
+    label: string;
+    type: string;
+    content: string;
+    /** Seconds, or 1 for automatic. */
+    ttl: number;
+    /** MX only; null otherwise. */
+    priority: number | null;
+    owner: 'organisation' | 'platform';
+    locked: boolean;
+    /** `pending`: still being set up. `removing`: teardown started. `removed`:
+     * the tombstone `records.remove` returns. */
+    state: 'pending' | 'active' | 'removing' | 'removed';
+}
+export interface RecordInput {
+    label: 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, 0 to 65535. */
+    priority?: number;
+}
+/** The label and type never change: remove the record and create another. */
+export interface RecordPatch {
+    content?: string;
+    data?: CaaData;
+    ttl?: number;
+    priority?: number;
+}
+export interface ListRecordsResponse {
+    records: RecordView[];
+}
+/** Why a records call answered `conflict`: `busy` (retry soon), `pending`
+ * (still being set up), `removing` (teardown in progress), or `taken` (the
+ * 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.2.0",
+  "version": "0.4.0",
   "type": "module",
   "license": "MIT",
   "description": "Public client SDK and API types for the edge service.",