@knowledgefutures/sdk 0.1.0 → 0.2.1

package/dist/analytics/types.d.ts

@@ -1,22 +0,0 @@
-import type { Cube, Query, QueryResult } from './cubes.js';
-import type { ServerHint } from './envelope.js';
-/** What project code holds. Every implementation — the collector, the memory double, `kf dev`'s log — is this. */
-export interface Analytics {
-    /**
-     * A server event, signed with the project's secret, so it counts as
-     * `source = 'server'`. For what matters: a download the project's Worker
-     * served, a sign-up. Pass the reader's `country` and `userAgent` when the
-     * server knows them.
-     */
-    track(event: ServerHint): Promise<void>;
-    /** The project's own numbers. Server-side only: the secret signs it. */
-    query<C extends Cube>(q: Query<C>): Promise<QueryResult>;
-    /**
-     * The `<script>` tag for the project's pages. `keyed` adds the public site
-     * id, for a project whose domains the console can't list. Empty under
-     * `kf dev` and in the memory double: nothing collects there.
-     */
-    beaconTag(options?: {
-        keyed?: boolean;
-    }): string;
-}

package/dist/analytics/types.js

@@ -1 +0,0 @@
-export {};

package/dist/storage/conformance.d.ts

@@ -1,24 +0,0 @@
-import type { Storage } from './types.js';
-/**
- * The storage conformance suite: what "same interface" means, as tests.
- * Every implementation — `memoryStorage`, RustFS under `kf dev`, R2 behind the
- * console — must pass all of it, or it is not offered. Project code written
- * against one therefore runs the same against the others.
- *
- *   describeStorageConformance('rustfs', async () => ({ storage, fetch }))
- *
- * Everything is written under a fresh `conformance/<uuid>/` prefix and
- * deleted afterwards, so the suite is safe against a real, shared bucket.
- */
-export interface ConformanceTarget {
-    storage: Storage;
-    /**
-     * How a browser would reach the URLs the store hands out (signed uploads,
-     * signed downloads, public objects). The global fetch for a real backend;
-     * `memoryStorage().fetch` for the in-memory store.
-     */
-    fetch: (input: string, init?: RequestInit) => Promise<Response>;
-    /** false when the environment doesn't declare `public`: the public tests then check it refuses. */
-    hasPublic?: boolean;
-}
-export declare function describeStorageConformance(name: string, setup: () => Promise<ConformanceTarget>): void;

package/dist/storage/conformance.js

@@ -1,311 +0,0 @@
-import { afterAll, beforeAll, describe, expect, it } from 'vitest';
-import { isStorageError } from './errors.js';
-export function describeStorageConformance(name, setup) {
-    describe(`storage conformance: ${name}`, () => {
-        let t;
-        const run = `conformance/${crypto.randomUUID()}/`;
-        const k = (key) => `${run}${key}`;
-        beforeAll(async () => {
-            t = await setup();
-        });
-        afterAll(async () => {
-            if (!t)
-                return;
-            const stores = [t.storage];
-            if (t.hasPublic !== false)
-                stores.push(t.storage.public);
-            for (const store of stores) {
-                let cursor;
-                do {
-                    const page = await store.list({ prefix: run, ...(cursor ? { cursor } : {}) });
-                    for (const o of page.objects)
-                        await store.delete(o.key);
-                    cursor = page.cursor;
-                } while (cursor);
-            }
-        });
-        describe('objects', () => {
-            it('put then get returns the bytes, type and metadata', async () => {
-                const put = await t.storage.put(k('a.bin'), new Uint8Array([0, 1, 2, 255]), {
-                    contentType: 'application/x-test',
-                    metadata: { owner: 'atlas', 'page-count': '3' },
-                    cacheControl: 'private, max-age=60',
-                });
-                expect(put).toMatchObject({ key: k('a.bin'), size: 4, contentType: 'application/x-test' });
-                expect(put.etag).not.toBe('');
-                const got = await t.storage.get(k('a.bin'));
-                expect(got).not.toBeNull();
-                expect([...new Uint8Array(await got.arrayBuffer())]).toEqual([0, 1, 2, 255]);
-                expect(got).toMatchObject({
-                    size: 4,
-                    contentType: 'application/x-test',
-                    cacheControl: 'private, max-age=60',
-                    metadata: { owner: 'atlas', 'page-count': '3' },
-                    etag: put.etag,
-                });
-            });
-            it('head agrees with put', async () => {
-                const put = await t.storage.put(k('head.txt'), 'hello');
-                const head = await t.storage.head(k('head.txt'));
-                expect(head).toMatchObject({
-                    key: k('head.txt'),
-                    size: 5,
-                    etag: put.etag,
-                    contentType: 'text/plain; charset=utf-8',
-                });
-                expect(Math.abs(head.uploaded.getTime() - put.uploaded.getTime())).toBeLessThan(5000);
-            });
-            it('accepts a Blob, taking its type, and a stream', async () => {
-                await t.storage.put(k('blob.json'), new Blob(['{"a":1}'], { type: 'application/json' }));
-                expect((await t.storage.head(k('blob.json')))?.contentType).toBe('application/json');
-                const stream = new Blob(['streamed']).stream();
-                await t.storage.put(k('stream.txt'), stream, { contentType: 'text/plain' });
-                expect(await (await t.storage.get(k('stream.txt'))).text()).toBe('streamed');
-            });
-            it('get and head of a missing key are null; deleting it is success', async () => {
-                expect(await t.storage.get(k('missing'))).toBeNull();
-                expect(await t.storage.head(k('missing'))).toBeNull();
-                await t.storage.delete(k('missing'));
-            });
-            it('delete removes; overwrite changes the etag', async () => {
-                const first = await t.storage.put(k('over.txt'), 'one');
-                const second = await t.storage.put(k('over.txt'), 'two!');
-                expect(second.etag).not.toBe(first.etag);
-                expect(await (await t.storage.get(k('over.txt'))).text()).toBe('two!');
-                await t.storage.delete(k('over.txt'));
-                expect(await t.storage.head(k('over.txt'))).toBeNull();
-            });
-            it('keys that need encoding round-trip exactly', async () => {
-                const keys = [
-                    'sp ace.txt',
-                    'plus+sign',
-                    'pct%20lit',
-                    'q?mark#hash',
-                    'ünï/cødé/文字',
-                    "quote'(paren)*",
-                ];
-                for (const key of keys)
-                    await t.storage.put(k(`enc/${key}`), key);
-                for (const key of keys)
-                    expect(await (await t.storage.get(k(`enc/${key}`))).text()).toBe(key);
-                const listed = (await t.storage.list({ prefix: k('enc/') })).objects.map((o) => o.key);
-                expect(listed.sort()).toEqual(keys.map((key) => k(`enc/${key}`)).sort());
-            });
-        });
-        describe('list', () => {
-            it('lists a prefix in key order, paged by cursor', async () => {
-                const names = ['e', 'a', 'c', 'b', 'd'];
-                for (const n of names)
-                    await t.storage.put(k(`list/${n}`), n);
-                await t.storage.put(k('listing-not-this'), 'x');
-                const seen = [];
-                let cursor;
-                let pages = 0;
-                do {
-                    const page = await t.storage.list({
-                        prefix: k('list/'),
-                        limit: 2,
-                        ...(cursor ? { cursor } : {}),
-                    });
-                    expect(page.objects.length).toBeLessThanOrEqual(2);
-                    seen.push(...page.objects.map((o) => o.key));
-                    cursor = page.cursor;
-                    pages++;
-                } while (cursor && pages < 10);
-                expect(seen).toEqual(['a', 'b', 'c', 'd', 'e'].map((n) => k(`list/${n}`)));
-                expect(pages).toBe(3);
-            });
-            it('reports size and etag', async () => {
-                const put = await t.storage.put(k('sized/one'), '12345');
-                const [o] = (await t.storage.list({ prefix: k('sized/') })).objects;
-                expect(o).toMatchObject({ key: k('sized/one'), size: 5, etag: put.etag });
-                expect(o.uploaded).toBeInstanceOf(Date);
-            });
-        });
-        describe('refusals are the same everywhere', () => {
-            it.each([
-                ['empty', ''],
-                ['a leading slash', '/abs'],
-                ['a .. segment', 'a/../b'],
-                ['a . segment', 'a/./b'],
-                ['a control character', 'a\u0001b'],
-                ['more than 1024 bytes', 'x'.repeat(1025)],
-            ])('a key with %s is invalid', async (_why, key) => {
-                await expect(t.storage.put(key, 'x')).rejects.toSatisfy((e) => isStorageError(e, 'invalid'));
-                await expect(t.storage.get(key)).rejects.toSatisfy((e) => isStorageError(e, 'invalid'));
-            });
-            it('every failure is a rejected promise, never a synchronous throw', async () => {
-                const calls = [
-                    () => t.storage.put('', 'x'),
-                    () => t.storage.upload(new Blob(['x']), { prefix: '/abs' }),
-                    () => t.storage.signUpload('', { contentType: 'text/plain', size: 1 }),
-                    () => t.storage.list({ limit: 0 }),
-                ];
-                for (const call of calls) {
-                    let promise;
-                    expect(() => {
-                        promise = call();
-                    }).not.toThrow();
-                    await expect(promise).rejects.toSatisfy((e) => isStorageError(e, 'invalid'));
-                }
-            });
-            it('a metadata name outside [a-z0-9-] is invalid', async () => {
-                await expect(t.storage.put(k('meta'), 'x', { metadata: { Bad_Name: 'x' } })).rejects.toSatisfy((e) => isStorageError(e, 'invalid'));
-            });
-        });
-        describe('upload', () => {
-            it('generates a key under the prefix, keeping the extension and type', async () => {
-                const file = new File(['cover'], 'Cover Art.JPG', { type: 'image/jpeg' });
-                const o = await t.storage.upload(file, { prefix: k('covers') });
-                expect(o.key).toMatch(new RegExp(`^${k('covers/')}[0-9a-f-]{36}\\.jpg$`));
-                expect(o.contentType).toBe('image/jpeg');
-                expect(await (await t.storage.get(o.key)).text()).toBe('cover');
-            });
-        });
-        describe('signed URLs', () => {
-            it('signUpload: a PUT with the signed headers and exact size lands', async () => {
-                const body = 'uploaded from a browser';
-                const up = await t.storage.signUpload(k('signed/ok.txt'), {
-                    contentType: 'text/plain',
-                    size: new TextEncoder().encode(body).length,
-                });
-                expect(up.method).toBe('PUT');
-                const res = await t.fetch(up.url, { method: 'PUT', headers: up.headers, body });
-                expect(res.status).toBeLessThan(300);
-                const got = await t.storage.get(k('signed/ok.txt'));
-                expect(await got.text()).toBe(body);
-                expect(got.contentType).toBe('text/plain');
-            });
-            it('signUpload: a different size or type is refused', async () => {
-                const up = await t.storage.signUpload(k('signed/strict.txt'), {
-                    contentType: 'text/plain',
-                    size: 5,
-                });
-                const tooBig = await t.fetch(up.url, { method: 'PUT', headers: up.headers, body: '123456' });
-                expect(tooBig.ok).toBe(false);
-                const wrongType = await t.fetch(up.url, {
-                    method: 'PUT',
-                    headers: { ...up.headers, 'content-type': 'text/html' },
-                    body: '12345',
-                });
-                expect(wrongType.ok).toBe(false);
-                expect(await t.storage.head(k('signed/strict.txt'))).toBeNull();
-            });
-            it('signDownload: GET returns the object, as an attachment when named', async () => {
-                await t.storage.put(k('signed/dl.txt'), 'download me');
-                const res = await t.fetch(await t.storage.signDownload(k('signed/dl.txt')));
-                expect(res.status).toBe(200);
-                expect(await res.text()).toBe('download me');
-                const named = await t.fetch(await t.storage.signDownload(k('signed/dl.txt'), { filename: 'Réport.txt' }));
-                expect(named.headers.get('content-disposition')).toContain('attachment');
-                expect(named.headers.get('content-disposition')).toContain('R%C3%A9port.txt');
-            });
-            it('an expired signed URL is refused', async () => {
-                await t.storage.put(k('signed/expiring.txt'), 'soon gone');
-                const url = await t.storage.signDownload(k('signed/expiring.txt'), { expiresIn: 2 });
-                expect((await t.fetch(url)).ok).toBe(true);
-                // The server judges expiry by its own clock, which can drift from
-                // ours (a container's VM, say): poll for the refusal rather than
-                // assume exactly when it comes.
-                let refused = false;
-                for (let waited = 0; !refused && waited < 10_000; waited += 500) {
-                    await new Promise((r) => setTimeout(r, 500));
-                    refused = !(await t.fetch(url)).ok;
-                }
-                expect(refused).toBe(true);
-            }, 15_000);
-            it('expiresIn outside 1–604800 seconds is invalid', async () => {
-                await expect(t.storage.signDownload(k('x'), { expiresIn: 604_801 })).rejects.toSatisfy((e) => isStorageError(e, 'invalid'));
-            });
-        });
-        describe('public store', () => {
-            it('is refused with not_configured when the environment has none', async () => {
-                if (t.hasPublic !== false)
-                    return;
-                expect(() => t.storage.public).toThrow(expect.objectContaining({ code: 'not_configured' }));
-            });
-            it('url(key) serves the object to anyone', async () => {
-                if (t.hasPublic === false)
-                    return;
-                await t.storage.public.put(k('pub/hello.txt'), 'public bytes', {
-                    contentType: 'text/plain',
-                });
-                const res = await t.fetch(t.storage.public.url(k('pub/hello.txt')));
-                expect(res.status).toBe(200);
-                expect(await res.text()).toBe('public bytes');
-                expect(res.headers.get('cache-control')).toBe('public, max-age=300');
-            });
-            it('upload() writes an immutable object at a fresh key', async () => {
-                if (t.hasPublic === false)
-                    return;
-                const o = await t.storage.public.upload(new Blob(['img'], { type: 'image/png' }), {
-                    prefix: k('pub/covers'),
-                });
-                expect(o.cacheControl).toBe('public, max-age=31536000, immutable');
-                const res = await t.fetch(t.storage.public.url(o.key));
-                expect(await res.text()).toBe('img');
-                expect(res.headers.get('cache-control')).toBe('public, max-age=31536000, immutable');
-            });
-            it('serves anything but raster images, audio and video as an attachment', async () => {
-                if (t.hasPublic === false)
-                    return;
-                const page = '<html><body>not a scam</body></html>';
-                const html = await t.storage.public.put(k('pub/page.html'), page, {
-                    contentType: 'text/html',
-                });
-                expect(html.contentDisposition).toMatch(/^attachment/);
-                const res = await t.fetch(t.storage.public.url(k('pub/page.html')));
-                expect(res.headers.get('content-disposition')).toMatch(/^attachment/);
-                expect(await res.text()).toBe(page);
-                // Asking for inline is not honoured for a type outside the list.
-                const svg = await t.storage.public.put(k('pub/logo.svg'), '<svg/>', {
-                    contentType: 'image/svg+xml',
-                    contentDisposition: 'inline',
-                });
-                expect(svg.contentDisposition).toMatch(/^attachment/);
-                // A caller's own attachment, with a file name, is kept.
-                const named = await t.storage.public.put(k('pub/r.pdf'), '%PDF', {
-                    contentType: 'application/pdf',
-                    contentDisposition: 'attachment; filename="report.pdf"',
-                });
-                expect(named.contentDisposition).toBe('attachment; filename="report.pdf"');
-                const png = await t.storage.public.put(k('pub/cover.png'), new Uint8Array([137, 80]), {
-                    contentType: 'image/png',
-                });
-                expect(png.contentDisposition).toBeUndefined();
-                const img = await t.fetch(t.storage.public.url(k('pub/cover.png')));
-                expect(img.headers.get('content-disposition')).toBeNull();
-            });
-            it('signs the attachment into a public upload, so a browser cannot drop it', async () => {
-                if (t.hasPublic === false)
-                    return;
-                const body = '<html></html>';
-                const up = await t.storage.public.signUpload(k('pub/up.html'), {
-                    contentType: 'text/html',
-                    size: body.length,
-                });
-                expect(up.headers['content-disposition']).toBe('attachment');
-                const { 'content-disposition': _dropped, ...without } = up.headers;
-                expect((await t.fetch(up.url, { method: 'PUT', headers: without, body })).ok).toBe(false);
-                expect((await t.fetch(up.url, { method: 'PUT', headers: up.headers, body })).ok).toBe(true);
-                expect((await t.storage.public.head(k('pub/up.html')))?.contentDisposition).toBe('attachment');
-                const img = await t.storage.public.signUpload(k('pub/up.webp'), {
-                    contentType: 'image/webp',
-                    size: 3,
-                });
-                expect(img.headers['content-disposition']).toBeUndefined();
-            });
-            it('leaves the private store alone', async () => {
-                const o = await t.storage.put(k('priv.html'), '<p>', { contentType: 'text/html' });
-                expect(o.contentDisposition).toBeUndefined();
-            });
-            it('the private and public stores are separate', async () => {
-                if (t.hasPublic === false)
-                    return;
-                await t.storage.put(k('pub/secret.txt'), 'private');
-                expect(await t.storage.public.head(k('pub/secret.txt'))).toBeNull();
-                expect((await t.fetch(t.storage.public.url(k('pub/secret.txt')))).ok).toBe(false);
-            });
-        });
-    });
-}

package/dist/storage/local.d.ts

@@ -1,26 +0,0 @@
-/**
- * Setting up a LOCAL S3 server — the one `kf dev` runs, or one in a test —
- * over the plain S3 API: create buckets, and let anyone read the public one.
- * No vendor CLI, so it works against any server that passes the conformance
- * suite (RustFS today). The console never uses this: deployed buckets are
- * provisioned by kf/storage@1's adapter through the provider's own API.
- */
-export interface LocalServer {
-    /** `http://localhost:<port>` */
-    endpoint: string;
-    accessKeyId: string;
-    secretAccessKey: string;
-    region?: string;
-}
-export interface LocalBucket {
-    name: string;
-    /** Anonymous GET on every object: the public store. */
-    publicRead?: boolean;
-}
-export interface EnsureOptions {
-    /** How long to wait for the server to accept connections. Default 30s. */
-    timeoutMs?: number;
-    fetch?: typeof fetch;
-}
-/** Idempotent: buckets that exist are left alone, and the policy is simply set again. */
-export declare function ensureBuckets(server: LocalServer, buckets: LocalBucket[], options?: EnsureOptions): Promise<void>;

package/dist/storage/local.js

@@ -1,57 +0,0 @@
-import { StorageError } from './errors.js';
-import { sha256Hex, signRequest } from './sigv4.js';
-/** Idempotent: buckets that exist are left alone, and the policy is simply set again. */
-export async function ensureBuckets(server, buckets, options = {}) {
-    const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
-    const credentials = {
-        accessKeyId: server.accessKeyId,
-        secretAccessKey: server.secretAccessKey,
-        region: server.region ?? 'us-east-1',
-    };
-    const deadline = Date.now() + (options.timeoutMs ?? 30_000);
-    const put = async (url, body = '') => {
-        for (;;) {
-            const headers = await signRequest({
-                method: 'PUT',
-                url,
-                payloadHash: await sha256Hex(body),
-                credentials,
-            });
-            try {
-                return await doFetch(url, { method: 'PUT', headers, ...(body ? { body } : {}) });
-            }
-            catch (e) {
-                // Not listening yet: the container has started, the server hasn't.
-                if (Date.now() > deadline) {
-                    throw new StorageError('unavailable', `${server.endpoint} never answered: ${e.message}`);
-                }
-                await new Promise((r) => setTimeout(r, 250));
-            }
-        }
-    };
-    for (const b of buckets) {
-        const res = await put(new URL(`${server.endpoint}/${b.name}`));
-        const text = await res.text();
-        if (!res.ok && !/BucketAlreadyOwnedByYou|BucketAlreadyExists/.test(text)) {
-            throw new StorageError('unavailable', `creating bucket ${b.name}: ${res.status} ${text.slice(0, 200)}`);
-        }
-        if (!b.publicRead)
-            continue;
-        const policy = JSON.stringify({
-            Version: '2012-10-17',
-            Statement: [
-                {
-                    Effect: 'Allow',
-                    Principal: { AWS: ['*'] },
-                    Action: ['s3:GetObject'],
-                    Resource: [`arn:aws:s3:::${b.name}/*`],
-                },
-            ],
-        });
-        const set = await put(new URL(`${server.endpoint}/${b.name}?policy=`), policy);
-        if (!set.ok) {
-            throw new StorageError('unavailable', `making ${b.name} publicly readable: ${set.status} ${(await set.text()).slice(0, 200)}`);
-        }
-        await set.body?.cancel();
-    }
-}