@knowledgefutures/sdk 0.0.0-stage → 0.2.1

package/dist/storage/testing.js

@@ -0,0 +1,242 @@
+import { StorageError } from './errors.js';
+import { attachment, checkExpiresIn, DOWNLOAD_EXPIRES_IN, UPLOAD_EXPIRES_IN, checkKey, checkMetadata, checkPrefix, checkSignUpload, IMMUTABLE, publicDisposition, SHORT_PUBLIC, toBytes, uploadAsPut, } from './shared.js';
+import { encodeKey } from './sigv4.js';
+const PRIVATE_ORIGIN = 'https://signed.storage.test';
+const DEFAULT_PUBLIC_BASE = 'https://public.storage.test';
+export function memoryStorage(options = {}) {
+    const grants = new Map();
+    const priv = new MemoryStore(grants, false);
+    const pub = options.public === false
+        ? null
+        : new MemoryStore(grants, true, (options.public?.base ?? DEFAULT_PUBLIC_BASE).replace(/\/+$/, ''));
+    async function serve(input, init) {
+        const req = new Request(input, init);
+        const url = new URL(req.url);
+        if (pub &&
+            req.url.startsWith(`${pub.base}/`) &&
+            (req.method === 'GET' || req.method === 'HEAD')) {
+            const key = decodeKey(url.pathname);
+            const e = pub.objects.get(key);
+            if (!e)
+                return new Response('not found', { status: 404 });
+            return objectResponse(e, req.method === 'HEAD');
+        }
+        if (url.origin !== PRIVATE_ORIGIN)
+            return new Response('not a URL this store handed out', { status: 404 });
+        const grant = grants.get(url.searchParams.get('kf-signature') ?? '');
+        if (!grant || grant.method !== req.method || grant.key !== decodeKey(url.pathname)) {
+            return new Response('SignatureDoesNotMatch', { status: 403 });
+        }
+        if (Date.now() > grant.expires)
+            return new Response('Request has expired', { status: 403 });
+        if (grant.method === 'GET') {
+            const e = grant.store.objects.get(grant.key);
+            if (!e)
+                return new Response('not found', { status: 404 });
+            const res = objectResponse(e, false);
+            if (grant.disposition)
+                res.headers.set('content-disposition', grant.disposition);
+            return res;
+        }
+        // PUT: exactly the signed headers, exactly the signed size.
+        const bytes = new Uint8Array(await req.arrayBuffer());
+        if (req.headers.get('content-type') !== grant.contentType ||
+            (req.headers.get('cache-control') ?? undefined) !== grant.cacheControl ||
+            (req.headers.get('content-disposition') ?? undefined) !== grant.disposition ||
+            bytes.byteLength !== grant.size) {
+            return new Response('SignatureDoesNotMatch', { status: 403 });
+        }
+        await grant.store.put(grant.key, bytes, {
+            contentType: grant.contentType,
+            ...(grant.cacheControl ? { cacheControl: grant.cacheControl } : {}),
+            ...(grant.disposition ? { contentDisposition: grant.disposition } : {}),
+        });
+        return new Response(null, { status: 200 });
+    }
+    return {
+        put: (key, body, o) => priv.put(key, body, o),
+        get: (key) => priv.get(key),
+        head: (key) => priv.head(key),
+        delete: (key) => priv.delete(key),
+        list: (o) => priv.list(o),
+        signUpload: (key, o) => priv.signUpload(key, o),
+        signDownload: (key, o) => priv.signDownload(key, o),
+        upload: (file, o) => priv.upload(file, o),
+        get public() {
+            if (!pub) {
+                throw new StorageError('not_configured', 'this store has no public store (memoryStorage({ public: false }))');
+            }
+            return pub;
+        },
+        fetch: serve,
+    };
+}
+class MemoryStore {
+    grants;
+    isPublic;
+    base;
+    objects = new Map();
+    constructor(grants, isPublic, base) {
+        this.grants = grants;
+        this.isPublic = isPublic;
+        this.base = base;
+    }
+    async put(key, body, opts = {}) {
+        checkKey(key);
+        const metadata = checkMetadata(opts.metadata);
+        const { bytes, contentType } = await toBytes(body, opts.contentType);
+        const cacheControl = opts.cacheControl ?? (this.isPublic ? SHORT_PUBLIC : undefined);
+        const disposition = this.isPublic
+            ? publicDisposition(contentType, opts.contentDisposition)
+            : opts.contentDisposition;
+        const e = {
+            key,
+            size: bytes.byteLength,
+            etag: crypto.randomUUID().replaceAll('-', ''),
+            uploaded: new Date(Math.floor(Date.now() / 1000) * 1000),
+            contentType,
+            metadata,
+            bytes,
+        };
+        if (cacheControl)
+            e.cacheControl = cacheControl;
+        if (disposition)
+            e.contentDisposition = disposition;
+        this.objects.set(key, e);
+        return describe(e);
+    }
+    async get(key) {
+        checkKey(key);
+        const e = this.objects.get(key);
+        if (!e)
+            return null;
+        const copy = e.bytes.slice();
+        return {
+            ...describe(e),
+            body: new Response(copy).body,
+            arrayBuffer: async () => copy.buffer.slice(0),
+            text: async () => new TextDecoder().decode(copy),
+        };
+    }
+    async head(key) {
+        checkKey(key);
+        const e = this.objects.get(key);
+        return e ? describe(e) : null;
+    }
+    async delete(key) {
+        checkKey(key);
+        this.objects.delete(key);
+    }
+    async list(opts = {}) {
+        checkPrefix(opts.prefix);
+        const limit = opts.limit ?? 1000;
+        if (!Number.isInteger(limit) || limit < 1 || limit > 1000) {
+            throw new StorageError('invalid', 'limit is 1–1000');
+        }
+        const after = opts.cursor ? decodeCursor(opts.cursor) : undefined;
+        const keys = [...this.objects.keys()]
+            .filter((k) => k.startsWith(opts.prefix ?? '') && (after === undefined || byteCompare(k, after) > 0))
+            .sort(byteCompare);
+        const page = keys.slice(0, limit);
+        const objects = page.map((k) => {
+            const e = this.objects.get(k);
+            return { key: e.key, size: e.size, etag: e.etag, uploaded: e.uploaded };
+        });
+        return keys.length > limit
+            ? { objects, cursor: btoa(encodeURIComponent(page.at(-1))) }
+            : { objects };
+    }
+    async signUpload(key, o) {
+        checkKey(key);
+        checkSignUpload(o);
+        const expiresIn = checkExpiresIn(o.expiresIn, UPLOAD_EXPIRES_IN);
+        const cacheControl = o.cacheControl ?? (this.isPublic ? SHORT_PUBLIC : undefined);
+        const headers = { 'content-type': o.contentType };
+        if (cacheControl)
+            headers['cache-control'] = cacheControl;
+        const disposition = this.isPublic ? publicDisposition(o.contentType, undefined) : undefined;
+        if (disposition)
+            headers['content-disposition'] = disposition;
+        const url = this.grant({
+            method: 'PUT',
+            key,
+            expiresIn,
+            contentType: o.contentType,
+            size: o.size,
+            ...(cacheControl ? { cacheControl } : {}),
+            ...(disposition ? { disposition } : {}),
+        });
+        return {
+            key,
+            url,
+            method: 'PUT',
+            headers,
+            expiresAt: new Date(Date.now() + expiresIn * 1000),
+        };
+    }
+    async signDownload(key, o = {}) {
+        checkKey(key);
+        const expiresIn = checkExpiresIn(o.expiresIn, DOWNLOAD_EXPIRES_IN);
+        return this.grant({
+            method: 'GET',
+            key,
+            expiresIn,
+            ...(o.filename ? { disposition: attachment(o.filename) } : {}),
+        });
+    }
+    async upload(file, options) {
+        const p = uploadAsPut(file, options, this.isPublic ? { cacheControl: IMMUTABLE } : {});
+        return this.put(p.key, p.body, p.options);
+    }
+    url(key) {
+        checkKey(key);
+        if (!this.base)
+            throw new StorageError('not_configured', 'the private store has no public URLs');
+        return `${this.base}/${encodeKey(key)}`;
+    }
+    grant(g) {
+        const token = crypto.randomUUID();
+        const { expiresIn, ...rest } = g;
+        this.grants.set(token, { ...rest, store: this, expires: Date.now() + expiresIn * 1000 });
+        return `${PRIVATE_ORIGIN}/${encodeKey(g.key)}?kf-signature=${token}`;
+    }
+}
+function describe(e) {
+    const { bytes: _bytes, ...meta } = e;
+    return { ...meta, metadata: { ...meta.metadata } };
+}
+function objectResponse(e, headOnly) {
+    const headers = new Headers({
+        'content-type': e.contentType,
+        'content-length': String(e.size),
+        etag: `"${e.etag}"`,
+        'last-modified': e.uploaded.toUTCString(),
+    });
+    if (e.cacheControl)
+        headers.set('cache-control', e.cacheControl);
+    if (e.contentDisposition)
+        headers.set('content-disposition', e.contentDisposition);
+    return new Response(headOnly ? null : e.bytes.slice(), { status: 200, headers });
+}
+function decodeKey(pathname) {
+    return pathname.slice(1).split('/').map(decodeURIComponent).join('/');
+}
+function decodeCursor(cursor) {
+    try {
+        return decodeURIComponent(atob(cursor));
+    }
+    catch {
+        throw new StorageError('invalid', 'not a cursor this store handed out');
+    }
+}
+const utf8 = new TextEncoder();
+/** S3 lists in UTF-8 byte order, which differs from UTF-16 `<` above the BMP. */
+function byteCompare(a, b) {
+    const x = utf8.encode(a);
+    const y = utf8.encode(b);
+    for (let i = 0; i < Math.min(x.length, y.length); i++) {
+        if (x[i] !== y[i])
+            return x[i] - y[i];
+    }
+    return x.length - y.length;
+}

package/dist/storage/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The storage interface every implementation honours: R2 behind the console,
+ * RustFS under `kf dev`, and `memoryStorage` in tests. Project code is written
+ * against these types only, and the conformance suite (conformance.ts) holds
+ * each implementation to them, so code that passes against one runs the same
+ * against the others.
+ *
+ * The surface is deliberately the subset all of them can honour: no POST
+ * policies (R2 has none), no per-object ACLs (R2 has none — public is a
+ * separate store), no multipart. Large files go browser → bucket through
+ * `signUpload`, never through the project's server.
+ */
+/** What `put` accepts. A stream is read to the end before upload; use `signUpload` for large files. */
+export type Body = string | ArrayBuffer | ArrayBufferView | Blob | ReadableStream<Uint8Array>;
+export interface PutOptions {
+    contentType?: string;
+    /** Sent back verbatim on every read — and, on the public store, what Cloudflare's cache obeys. */
+    cacheControl?: string;
+    contentDisposition?: string;
+    /** Lowercase `[a-z0-9-]` keys. Small: S3 caps all metadata at 2 KB. */
+    metadata?: Record<string, string>;
+}
+/** One object as a `list` returns it: only what every backend's listing reports. */
+export interface ListedObject {
+    key: string;
+    size: number;
+    /** Opaque. Stable while the object is unchanged; changes when it is overwritten. */
+    etag: string;
+    uploaded: Date;
+}
+/** One object as `put` and `head` report it. */
+export interface StoredObject extends ListedObject {
+    contentType: string;
+    cacheControl?: string;
+    contentDisposition?: string;
+    metadata: Record<string, string>;
+}
+export interface ObjectBody extends StoredObject {
+    body: ReadableStream<Uint8Array>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+}
+export interface ListOptions {
+    prefix?: string;
+    /** From the previous page's `cursor`. Opaque. */
+    cursor?: string;
+    /** 1–1000. Default 1000. */
+    limit?: number;
+}
+export interface ListResult {
+    /** In key order (UTF-8 byte order). */
+    objects: ListedObject[];
+    /** Present when there is another page. */
+    cursor?: string;
+}
+export interface SignUploadOptions {
+    contentType: string;
+    /** The exact byte length. It is signed, so the upload must be exactly this size. */
+    size: number;
+    /**
+     * Seconds. Default 600. Up to 604800 with fixed credentials (`kf dev`, tests);
+     * on the console, at most the storage service's credential lifetime (an hour),
+     * because a signed URL stops working when the credentials that signed it expire.
+     */
+    expiresIn?: number;
+    cacheControl?: string;
+}
+/** What a browser needs to upload: PUT the file to `url` with exactly these headers. */
+export interface SignedUpload {
+    key: string;
+    url: string;
+    method: 'PUT';
+    headers: Record<string, string>;
+    expiresAt: Date;
+}
+export interface SignDownloadOptions {
+    /** Seconds. Default 300. The same limits as `SignUploadOptions.expiresIn`. */
+    expiresIn?: number;
+    /** Served as an attachment with this file name. */
+    filename?: string;
+}
+/** A file with a name, for `upload`. A `File` is one. */
+export interface Upload {
+    body: Body;
+    contentType?: string;
+    /** Its extension carries over to the generated key. */
+    name?: string;
+}
+export interface UploadOptions {
+    /** The key is `<prefix>/<uuid><ext>`. */
+    prefix?: string;
+    cacheControl?: string;
+    metadata?: Record<string, string>;
+}
+export interface Store {
+    put(key: string, body: Body, options?: PutOptions): Promise<StoredObject>;
+    /** null when there is no such object. */
+    get(key: string): Promise<ObjectBody | null>;
+    /** null when there is no such object. */
+    head(key: string): Promise<StoredObject | null>;
+    /** Deleting what is not there is success. */
+    delete(key: string): Promise<void>;
+    list(options?: ListOptions): Promise<ListResult>;
+    signUpload(key: string, options: SignUploadOptions): Promise<SignedUpload>;
+    signDownload(key: string, options?: SignDownloadOptions): Promise<string>;
+    /** A generated key, so nothing is ever overwritten by accident. */
+    upload(file: Blob | Upload, options?: UploadOptions): Promise<StoredObject>;
+}
+/**
+ * The public store: everything in it is readable by anyone at `url(key)`,
+ * through Cloudflare's cache and with no signature. Treat its keys as
+ * immutable — an overwrite or delete is seen only after the object's
+ * `max-age`, since nothing purges the cache.
+ */
+export interface PublicStore extends Store {
+    /** Where anyone can GET the object. Synchronous: no network, no signing. */
+    url(key: string): string;
+}
+export interface Storage extends Store {
+    /** Throws `not_configured` unless the manifest declares `"public": true`. */
+    readonly public: PublicStore;
+}

package/dist/storage/types.js

@@ -0,0 +1,13 @@
+/**
+ * The storage interface every implementation honours: R2 behind the console,
+ * RustFS under `kf dev`, and `memoryStorage` in tests. Project code is written
+ * against these types only, and the conformance suite (conformance.ts) holds
+ * each implementation to them, so code that passes against one runs the same
+ * against the others.
+ *
+ * The surface is deliberately the subset all of them can honour: no POST
+ * policies (R2 has none), no per-object ACLs (R2 has none — public is a
+ * separate store), no multipart. Large files go browser → bucket through
+ * `signUpload`, never through the project's server.
+ */
+export {};

package/dist/whistle/hono.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `app.use(whistle())`: Hono middleware for what a tailed Worker's runs don't
+ * say by themselves. Typed by shape, so the SDK doesn't depend on Hono.
+ *
+ *   403s, and 401s to a request that presented a credential → `access.denied`
+ *   writes under /admin that succeed                       → `admin.action`
+ *   an error a custom onError turned into a 5xx            → console.error, for the tail
+ *
+ * The user comes from `c.var.user.id` unless `user` says otherwise.
+ */
+import { type Sink } from './index.js';
+/**
+ * The parts of Hono's Context this reads. `var` is loose so a `user` option
+ * reads the app's variables untyped; `whistle<Context<AppEnv>>()` types them.
+ */
+export interface HonoContextLike {
+    req: {
+        raw: Request;
+        method: string;
+        path: string;
+        routePath: string;
+    };
+    res: Response;
+    env: unknown;
+    error: Error | undefined;
+    var: any;
+}
+export interface WhistleOptions<C extends HonoContextLike = HonoContextLike> {
+    /** The console project key, e.g. `kf/pilot`. Default: `KF_WHISTLE_PROJECT`, which the console sets. */
+    project?: string;
+    /** Default: `KF_WHISTLE_ENVIRONMENT`, which the console sets, else `production`. */
+    environment?: string;
+    /** The signed-in user's id, if any; asked only when there's an event. Default: `c.var.user?.id`. */
+    user?: (c: C) => string | null | undefined | Promise<string | null | undefined>;
+    /** Path prefixes whose successful writes are recorded. Default `/admin`, `/api/admin`; false for none. */
+    admin?: string[] | false;
+    /** Where `KF_*` variables come from. Default: `c.env`, then `process.env`. */
+    env?: Record<string, unknown>;
+    /** Tests: where events go instead of Whistle. */
+    sink?: Sink;
+}
+export declare function whistle<C extends HonoContextLike = HonoContextLike>(options?: WhistleOptions<C>): (c: C, next: () => Promise<void>) => Promise<void>;

package/dist/whistle/hono.js

@@ -0,0 +1,89 @@
+/**
+ * `app.use(whistle())`: Hono middleware for what a tailed Worker's runs don't
+ * say by themselves. Typed by shape, so the SDK doesn't depend on Hono.
+ *
+ *   403s, and 401s to a request that presented a credential → `access.denied`
+ *   writes under /admin that succeed                       → `admin.action`
+ *   an error a custom onError turned into a 5xx            → console.error, for the tail
+ *
+ * The user comes from `c.var.user.id` unless `user` says otherwise.
+ */
+import { defined, requestFields, telemetryFromEnv } from './index.js';
+const WRITES = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const NAMES = [
+    'KF_WHISTLE_URL',
+    'KF_WHISTLE_PROJECT',
+    'KF_WHISTLE_ENVIRONMENT',
+    'KF_DEPLOYMENT_ID',
+    'KF_COMMIT',
+];
+const record = (v) => v && typeof v === 'object' ? v : undefined;
+const processEnv = () => record(globalThis.process?.env) ?? {};
+function variables(c, given) {
+    const out = {};
+    const sources = given ? [given] : [record(c.env) ?? {}, processEnv()];
+    for (const name of NAMES) {
+        const found = sources.map((s) => s[name]).find((v) => typeof v === 'string' && v);
+        if (found !== undefined)
+            out[name] = found;
+    }
+    return out;
+}
+/** `c.executionCtx` throws outside Workers. */
+function waitUntilOf(c) {
+    try {
+        const ctx = c.executionCtx;
+        return ctx ? (p) => ctx.waitUntil(p) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function defaultUser(c) {
+    const id = record(record(c.var)?.user)?.id;
+    return typeof id === 'string' || typeof id === 'number' ? String(id) : undefined;
+}
+const under = (path, prefixes) => prefixes.some((p) => path === p || path.startsWith(`${p}/`));
+let warned = false;
+export function whistle(options = {}) {
+    const admin = options.admin === false ? [] : (options.admin ?? ['/admin', '/api/admin']);
+    return async (c, next) => {
+        await next();
+        try {
+            const status = c.res.status;
+            const waitUntil = waitUntilOf(c);
+            // On a Worker the tail reads this; it drops a second copy of an error in the same run.
+            if (c.error && status >= 500 && waitUntil)
+                console.error(c.error);
+            const method = c.req.method.toUpperCase();
+            const denied = status === 403 || (status === 401 && c.req.raw.headers.has('authorization'));
+            const adminWrite = status < 400 && WRITES.has(method) && under(c.req.path, admin);
+            if (!denied && !adminWrite)
+                return;
+            const env = variables(c, options.env);
+            if (!options.project && !env.KF_WHISTLE_PROJECT) {
+                if (!warned) {
+                    warned = true;
+                    console.warn('whistle(): no project; pass { project } or redeploy through the console');
+                }
+                return;
+            }
+            const t = telemetryFromEnv(env, defined({
+                project: options.project,
+                environment: options.environment,
+                sink: options.sink,
+                waitUntil,
+            }));
+            const id = await (options.user ?? defaultUser)(c);
+            t.securityEvent(denied ? 'access.denied' : 'admin.action', {
+                ...defined({ actor: id ? `user:${id}` : undefined }),
+                ...requestFields(c.req.raw),
+                ...(denied ? { outcome: 'denied' } : {}),
+                detail: { method, route: c.req.routePath, status },
+            });
+        }
+        catch {
+            // Telemetry never breaks the request it describes.
+        }
+    };
+}

package/dist/whistle/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `@knowledgefutures/sdk/whistle` — what a project that declares
+ * `kf/whistle@1` tells Whistle beyond what its Worker's runs already say.
+ * On a Worker the console hosts, Whistle tails every run, so uncaught
+ * exceptions, `console.error(err)` and cron runs need nothing from here.
+ * This is for security events, errors the app handles without logging, and
+ * check-ins from jobs that aren't Worker crons:
+ *
+ *   app.use(whistle()) // Hono: denied requests and admin writes (hono.ts)
+ *   const t = telemetryFromEnv(env, { waitUntil })
+ *   t.securityEvent('auth.failed', { actor: `user:${id}`, ...requestFields(request) })
+ *   await checkIn(env.KF_WHISTLE_URL, 'nightly-backup', { every: 1440 })
+ *
+ * With `KF_WHISTLE_URL` (the console hands it out) events go straight to
+ * Whistle; without it, to the console as JSON lines. Moved here from
+ * kf-whistle's `@kf/telemetry`, which Whistle keeps for parsing until it
+ * reads this package instead: the wire format (wire.ts) must not drift
+ * between the two.
+ */
+import { type SecurityEvent, type SecurityKind, type WireEvent } from './wire.js';
+export * from './wire.js';
+export interface Sink {
+    emit(event: WireEvent): void;
+}
+/** Workers (and anything whose stdout is collected): one JSON line per event. */
+export declare const consoleSink: Sink;
+/** Every event to each sink. */
+export declare function teeSink(...sinks: Sink[]): Sink;
+export interface WhistleTarget {
+    /** Whistle's origin, e.g. https://whistle.kfutures.org. */
+    origin: string;
+    /** The ingest key, sent as a bearer. */
+    key: string;
+}
+/** `KF_WHISTLE_URL` (`https://<instance>:<key>@<host>/`) as an origin and a key, or null. */
+export declare function parseWhistleUrl(url: string | undefined): WhistleTarget | null;
+/**
+ * A Sentry DSN that sends to Whistle, from `KF_WHISTLE_URL`: how an app on a
+ * Sentry SDK moves without code changes beyond `dsn` (and `release:
+ * KF_DEPLOYMENT_ID`, so errors group by deployment). Null without a URL, or
+ * when the key isn't one a DSN can carry (Sentry takes only [A-Za-z0-9_]).
+ * The project id is a placeholder: Sentry wants a number, Whistle goes by the key.
+ */
+export declare function sentryDsn(url: string | undefined): string | null;
+/**
+ * Reports one run of a scheduled job to Whistle: `every` (minutes) says how
+ * often it should run, so Whistle can say when it stops. Never throws; false
+ * when there's no KF_WHISTLE_URL or the send failed.
+ *
+ *   await checkIn(env.KF_WHISTLE_URL, 'nightly-backup', { every: 1440 })
+ *   await checkIn(env.KF_WHISTLE_URL, 'nightly-backup', { status: 'error', message: String(e) })
+ */
+export declare function checkIn(url: string | undefined, name: string, run?: {
+    status?: 'ok' | 'error';
+    every?: number;
+    grace?: number;
+    message?: string;
+}, doFetch?: typeof fetch): Promise<boolean>;
+export interface WhistleSinkOptions {
+    fetch?: typeof fetch;
+    /** On Workers, the request's `ctx.waitUntil`, so the send outlives the response. */
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * Posts events to Whistle's `/v1/events` as NDJSON, batched per tick. `flush()`
+ * sends what's queued now; failures are dropped, never thrown.
+ */
+export declare function whistleSink(target: WhistleTarget, options?: WhistleSinkOptions): Sink & {
+    flush(): Promise<void>;
+};
+export interface TelemetryOptions {
+    project: string;
+    environment: string;
+    sink?: Sink;
+    now?: () => Date;
+    /** The console's deployment id and commit, stamped on every event. */
+    deployment?: string;
+    commit?: string;
+}
+/**
+ * Telemetry set up from what the console hands a project: `KF_WHISTLE_URL`
+ * (sends straight to Whistle), `KF_WHISTLE_PROJECT` and `KF_WHISTLE_ENVIRONMENT`
+ * (what Whistle files events under), `KF_DEPLOYMENT_ID` and `KF_COMMIT`.
+ * Without `KF_WHISTLE_URL`, console output. Not both: on Workers, Cloudflare's
+ * export would deliver the console line as well, and every event would count twice.
+ */
+export declare function telemetryFromEnv(env: Record<string, unknown>, options?: Partial<Omit<TelemetryOptions, 'deployment' | 'commit'>> & WhistleSinkOptions): Telemetry;
+export interface SecurityFields {
+    actor?: string;
+    ip?: string;
+    country?: string;
+    role?: string;
+    outcome?: SecurityEvent['outcome'];
+    rayId?: string;
+    traceId?: string;
+    detail?: Record<string, unknown>;
+}
+export interface ErrorContext {
+    route?: string;
+    rayId?: string;
+    traceId?: string;
+    detail?: Record<string, unknown>;
+}
+export interface Telemetry {
+    securityEvent(kind: SecurityKind, fields?: SecurityFields): void;
+    captureError(error: unknown, context?: ErrorContext): void;
+    /** Runs `fn`; if it throws, records the error with `name` as its route, then rethrows. */
+    span<T>(name: string, fn: () => T | Promise<T>, context?: ErrorContext): Promise<T>;
+}
+/** `T` with its possibly-undefined properties made optional and non-undefined, as `defined` returns it. */
+export type Defined<T> = {
+    [K in keyof T as undefined extends T[K] ? never : K]: T[K];
+} & {
+    [K in keyof T as undefined extends T[K] ? K : never]?: Exclude<T[K], undefined>;
+};
+/** `{ ...o }` without the undefined values, so events stay small and exact. */
+export declare function defined<T extends object>(o: T): Defined<T>;
+/** An Error, or whatever was thrown, as the three exception fields. */
+export declare function describeError(error: unknown): {
+    type: string;
+    message: string;
+    stack?: string;
+};
+export declare function createTelemetry(options: TelemetryOptions): Telemetry;
+/**
+ * What a request carries that events want, on Cloudflare: the client IP, its
+ * country, and the Ray ID that joins an event to its edge log row. Elsewhere,
+ * pass them yourself.
+ */
+export declare function requestFields(request: Request): {
+    ip?: string;
+    country?: string;
+    rayId?: string;
+};
+export { whistle, type HonoContextLike, type WhistleOptions } from './hono.js';