@wtfalch/edge 0.2.0 → 0.3.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,20 @@ 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);
+```
+
 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,26 @@
 import { type ClientOptions } from './transport.js';
-import type { AvailableResponse, ClaimNameRequest, ListClaimsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OrgSettingsRequest, TokenResponse } from './types.js';
+import type { AvailableResponse, ClaimNameRequest, ListClaimsResponse, ListRecordsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OrgSettingsRequest, RecordInput, RecordPatch, RecordView, TokenResponse } 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>;
+    };
     /** 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,22 @@ 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)}`),
+        },
         /** 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,57 @@ 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'>;

package/package.json

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