@substrat-run/adapter-cloudflare 0.91.1 → 0.92.1

package/dist/client-context.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The Cloudflare read of "who is on the other end" — normalised ONCE, here.
+ *
+ * Cloudflare puts what it knows about a request's origin on `request.cf`: country,
+ * region, city, timezone, and a dozen more fields (colo, ASN, TLS version, bot
+ * score) that answer questions a vertical does not ask. This is the only place the
+ * platform reads that object. Everything above it — a host's harness, a vertical's
+ * operation input, a row in a table — sees `ClientContext` from contracts, and would
+ * see the identical shape from a node dev server or a future edge that says the same
+ * things in headers.
+ *
+ * What is normalised, and why:
+ *
+ *   - `country` `T1` (Tor) and `XX` (unknown) are Cloudflare's sentinels, not
+ *     countries. They become null rather than a two-letter code a UI would try to
+ *     render as a flag.
+ *   - `region` is the NAME (`Stockholm County`), not `regionCode`; codes are
+ *     per-country schemes and a person reads the name.
+ *   - Every field is a string or absent on `cf`, and absent on a request that did not
+ *     come through the edge (`wrangler dev`, the vitest pool) — so each is read
+ *     defensively and missing means null, never a throw.
+ *   - Latitude, longitude and postal code are NOT carried. They locate a person to a
+ *     street, and nothing a support desk does needs more than the city.
+ *
+ * `IncomingRequestCfProperties` is typed loosely (`unknown`) at the seam on purpose:
+ * the workers-types shape has changed between majors, and a structural read that
+ * tolerates a missing field survives that where a typed one would not compile.
+ */
+import { type ClientContext, type ClientGeo } from '@substrat-run/contracts';
+/** What a Worker's `Request` carries beyond the standard: the edge's own facts. */
+export interface CloudflareRequestLike {
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    readonly cf?: unknown;
+}
+/**
+ * The geo half of `request.cf`, in the platform's shape.
+ *
+ * Takes the `cf` object rather than the request so a caller holding the object some
+ * other way (a queued job that stashed it, a test) can use it too.
+ */
+export declare function cloudflareGeo(cf: unknown): ClientGeo;
+/** The whole `ClientContext` for a request that came through Cloudflare's edge. */
+export declare function cloudflareClientContext(request: CloudflareRequestLike): ClientContext;
+//# sourceMappingURL=client-context.d.ts.map

package/dist/client-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-context.d.ts","sourceRoot":"","sources":["../src/client-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAA8B,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzG,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACvD,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;CACvB;AASD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,SAAS,CAYpD;AAED,mFAAmF;AACnF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,qBAAqB,GAAG,aAAa,CAErF"}

package/dist/client-context.js

@@ -0,0 +1,59 @@
+/**
+ * The Cloudflare read of "who is on the other end" — normalised ONCE, here.
+ *
+ * Cloudflare puts what it knows about a request's origin on `request.cf`: country,
+ * region, city, timezone, and a dozen more fields (colo, ASN, TLS version, bot
+ * score) that answer questions a vertical does not ask. This is the only place the
+ * platform reads that object. Everything above it — a host's harness, a vertical's
+ * operation input, a row in a table — sees `ClientContext` from contracts, and would
+ * see the identical shape from a node dev server or a future edge that says the same
+ * things in headers.
+ *
+ * What is normalised, and why:
+ *
+ *   - `country` `T1` (Tor) and `XX` (unknown) are Cloudflare's sentinels, not
+ *     countries. They become null rather than a two-letter code a UI would try to
+ *     render as a flag.
+ *   - `region` is the NAME (`Stockholm County`), not `regionCode`; codes are
+ *     per-country schemes and a person reads the name.
+ *   - Every field is a string or absent on `cf`, and absent on a request that did not
+ *     come through the edge (`wrangler dev`, the vitest pool) — so each is read
+ *     defensively and missing means null, never a throw.
+ *   - Latitude, longitude and postal code are NOT carried. They locate a person to a
+ *     street, and nothing a support desk does needs more than the city.
+ *
+ * `IncomingRequestCfProperties` is typed loosely (`unknown`) at the seam on purpose:
+ * the workers-types shape has changed between majors, and a structural read that
+ * tolerates a missing field survives that where a typed one would not compile.
+ */
+import { clientContextOf, EMPTY_GEO } from '@substrat-run/contracts';
+const NOT_A_COUNTRY = new Set(['T1', 'XX']);
+function str(cf, key) {
+    const v = cf[key];
+    return typeof v === 'string' && v.trim() !== '' ? v.trim() : null;
+}
+/**
+ * The geo half of `request.cf`, in the platform's shape.
+ *
+ * Takes the `cf` object rather than the request so a caller holding the object some
+ * other way (a queued job that stashed it, a test) can use it too.
+ */
+export function cloudflareGeo(cf) {
+    if (!cf || typeof cf !== 'object')
+        return EMPTY_GEO;
+    const o = cf;
+    const country = str(o, 'country');
+    const continent = str(o, 'continent');
+    return {
+        country: country && /^[A-Z]{2}$/.test(country) && !NOT_A_COUNTRY.has(country) ? country : null,
+        region: str(o, 'region'),
+        city: str(o, 'city'),
+        timezone: str(o, 'timezone'),
+        continent: continent && /^[A-Z]{2}$/.test(continent) ? continent : null,
+    };
+}
+/** The whole `ClientContext` for a request that came through Cloudflare's edge. */
+export function cloudflareClientContext(request) {
+    return clientContextOf(request.headers, cloudflareGeo(request.cf));
+}
+//# sourceMappingURL=client-context.js.map

package/dist/client-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-context.js","sourceRoot":"","sources":["../src/client-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,eAAe,EAAE,SAAS,EAAsC,MAAM,yBAAyB,CAAC;AAQzG,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;AAE5C,SAAS,GAAG,CAAC,EAA2B,EAAE,GAAW;IACnD,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IAClB,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACpE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,EAAW;IACvC,IAAI,CAAC,EAAE,IAAI,OAAO,EAAE,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACpD,MAAM,CAAC,GAAG,EAA6B,CAAC;IACxC,MAAM,OAAO,GAAG,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IACtC,OAAO;QACL,OAAO,EAAE,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;QAC9F,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC;QACxB,IAAI,EAAE,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC;QAC5B,SAAS,EAAE,SAAS,IAAI,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;KACxE,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,uBAAuB,CAAC,OAA8B;IACpE,OAAO,eAAe,CAAC,OAAO,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;AACrE,CAAC"}

package/dist/index.d.ts

@@ -31,4 +31,6 @@ export type { R2BlobStores, R2BlobStoresOptions } from './r2.js';
 export { createRouteResolver } from './route-resolver.js';
 export type { RouteResolver } from './route-resolver.js';
 export type { ControlPlaneReader, DoCheckerDeps } from './checker.js';
+export { cloudflareClientContext, cloudflareGeo } from './client-context.js';
+export type { CloudflareRequestLike } from './client-context.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC1F,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACjF,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACrE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC1F,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACjF,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACrE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC7E,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -24,4 +24,5 @@ export { defineScopeSweeperDO, SCOPE_SWEEPER_NAME } from './scope-sweeper-do.js'
 export { createD1TenantStores, d1TenantRelationalStore, tenantStoreDatabaseName, } from './d1.js';
 export { blobStoreBucketName, createR2BlobStores, r2TenantBlobStore, } from './r2.js';
 export { createRouteResolver } from './route-resolver.js';
+export { cloudflareClientContext, cloudflareGeo } from './client-context.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAE1F,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAQjF,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAE1F,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAQjF,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@substrat-run/adapter-cloudflare",
-  "version": "0.91.1",
+  "version": "0.92.1",
   "description": "Cloudflare Durable-Object scope host (D-14): DO-per-scope, real kernel semantics on Workers",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -26,8 +26,8 @@
     "dist"
   ],
   "dependencies": {
-    "@substrat-run/contracts": "^0.91.1",
-    "@substrat-run/kernel": "^0.91.1"
+    "@substrat-run/contracts": "^0.92.1",
+    "@substrat-run/kernel": "^0.92.1"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.9.0",
@@ -35,7 +35,7 @@
     "typescript": "^7.0.0",
     "vitest": "^3.2.7",
     "wrangler": "^4.110.0",
-    "@substrat-run/contract-tests": "^0.91.1"
+    "@substrat-run/contract-tests": "^0.92.1"
   },
   "publishConfig": {
     "access": "public"