@north-light/sdk 0.3.548 → 0.3.550

package/dist/testing/space.js

@@ -0,0 +1,265 @@
+import { builtinDefinitions, droppedRelations, factKey, formatSubject, holds, parseResource, parseSubject, validateFact, validateSchema, OBJECT_TYPE } from './permissions.js';
+import { invalid, notFound, objectBody, refuse } from './wire.js';
+export const SPACE_OPS = new Set(['schema.register', 'relations.write', 'relations.replace', 'relations.list', 'check', 'doc.write', 'doc.edit', 'doc.delete', 'object.list', 'object.search', 'object.get']);
+const str = (value, field) => { if (typeof value !== 'string')
+    throw invalid(`${field} must be a string`, field); return value; };
+const factDto = (f) => ({ resource: `${f.resourceType}:${f.resourceId}`, relation: f.relation, subject: formatSubject(f.subject) });
+export class FakeSpace {
+    clientId;
+    userId;
+    now;
+    schemas = new Map();
+    facts = new Map();
+    docs = new Map();
+    serial = 0;
+    constructor(clientId, userId, now) {
+        this.clientId = clientId;
+        this.userId = userId;
+        this.now = now;
+    }
+    clear() { this.schemas.clear(); this.facts.clear(); this.docs.clear(); }
+    /** The built-in definitions plus every registered app definition. */
+    definitions() {
+        const defs = builtinDefinitions();
+        for (const { defs: registered } of this.schemas.values())
+            for (const d of registered)
+                defs.set(d.name, d);
+        return defs;
+    }
+    handle(op, id, query, rawBody) {
+        switch (op) {
+            case 'schema.register': return { status: 200, body: this.register(objectBody(rawBody)) };
+            case 'relations.write': return { status: 200, body: this.change(objectBody(rawBody)) };
+            case 'relations.replace': return { status: 200, body: this.replace(objectBody(rawBody)) };
+            case 'relations.list': return { status: 200, body: this.list(query.get('resource')) };
+            case 'check': return { status: 200, body: this.check(objectBody(rawBody)) };
+            case 'doc.write': return { status: 200, body: this.write(objectBody(rawBody)) };
+            case 'doc.edit': return { status: 200, body: this.edit(this.byRef(id), objectBody(rawBody)) };
+            case 'doc.delete': return { status: 200, body: this.remove(this.byRef(id)) };
+            case 'object.list': return { status: 200, body: { items: this.filter(query.get('name'), query.get('schema_type'), query.get('extensions') === null ? undefined : this.json(query.get('extensions')), query.get('kind'), Number(query.get('limit') ?? 50)).map((d) => this.item(d)), next_cursor: null } };
+            case 'object.search': return { status: 200, body: this.search(objectBody(rawBody)) };
+            case 'object.get': return { status: 200, body: this.read(this.byRef(id)) };
+        }
+    }
+    json(text) { try {
+        return objectBody(JSON.parse(text));
+    }
+    catch {
+        throw invalid('extensions must be a JSON object', 'extensions');
+    } }
+    ownerHandle(doc) { return doc.owner === 'app' ? this.clientId : this.userId.replace(/^user:/, ''); }
+    canonical(doc) { return `${this.ownerHandle(doc)}/${doc.name}`; }
+    byRef(ref) {
+        const doc = [...this.docs.values()].find((d) => d.id === ref || this.canonical(d) === ref);
+        if (!doc)
+            throw notFound(`no document ${ref}`);
+        return doc;
+    }
+    /** A resource type `<namespace>/<name>` must live in a namespace this app registered. */
+    owned(type) {
+        if (!type.includes('/') || !this.schemas.has(type.split('/')[0]))
+            throw refuse(403, 'not_schema_owner', `${type} is not in a namespace this app registered`, { details: { type } });
+    }
+    register(b) {
+        const namespace = str(b['namespace'], 'namespace');
+        const source = str(b['source'], 'source');
+        const defs = validateSchema(namespace, source);
+        const held = this.schemas.get(namespace);
+        if (held?.source === source)
+            return { namespace, version: held.version, changed: false };
+        if (held !== undefined) {
+            for (const { definition, relation } of droppedRelations(held.defs, defs)) {
+                const facts = [...this.facts.values()].filter((f) => f.resourceType === definition && f.relation === relation).length;
+                if (facts > 0)
+                    throw refuse(409, 'relation_in_use', `${definition}#${relation} still holds ${facts} facts; delete them first`, { details: { relation: `${definition}#${relation}`, facts } });
+            }
+        }
+        const version = (held?.version ?? 0) + 1;
+        this.schemas.set(namespace, { source, version, defs });
+        return { namespace, version, changed: true };
+    }
+    factList(value, field) {
+        if (value === undefined)
+            return [];
+        if (!Array.isArray(value))
+            throw invalid(`${field} must be a list`, field);
+        return value.map((f) => { const o = objectBody(f); return { resource: str(o['resource'], 'resource'), relation: str(o['relation'], 'relation'), subject: str(o['subject'], 'subject') }; });
+    }
+    fact(f) {
+        const r = parseResource(f.resource);
+        this.owned(r.type);
+        return { resourceType: r.type, resourceId: r.id, relation: f.relation, subject: parseSubject(f.subject) };
+    }
+    /** Validate and apply facts to `into`, in order; false when the fact was already there. */
+    put(into, fact) {
+        validateFact(this.definitions(), fact);
+        if (into.has(factKey(fact)))
+            return false;
+        into.set(factKey(fact), fact);
+        return true;
+    }
+    // A refusal anywhere leaves the facts as they were: the daemon runs each request in one transaction.
+    change(b) {
+        const write = this.factList(b['write'], 'write');
+        const remove = this.factList(b['delete'], 'delete');
+        const next = new Map(this.facts);
+        let written = 0;
+        let deleted = 0;
+        for (const f of write)
+            if (this.put(next, this.fact(f)))
+                written++;
+        for (const f of remove)
+            if (next.delete(factKey(this.fact(f))))
+                deleted++;
+        this.facts = next;
+        return { written, deleted };
+    }
+    replace(b) {
+        const resource = str(b['resource'], 'resource');
+        const relation = str(b['relation'], 'relation');
+        const subjects = b['subjects'];
+        if (!Array.isArray(subjects))
+            throw invalid('subjects must be a list', 'subjects');
+        const { type, id } = parseResource(resource);
+        this.owned(type);
+        const wanted = new Map(subjects.map((s) => parseSubject(str(s, 'subjects'))).map((s) => [formatSubject(s), s]));
+        const next = new Map(this.facts);
+        let written = 0;
+        let deleted = 0;
+        for (const [key, f] of this.facts)
+            if (f.resourceType === type && f.resourceId === id && f.relation === relation && !wanted.has(formatSubject(f.subject))) {
+                next.delete(key);
+                deleted++;
+            }
+        for (const subject of wanted.values())
+            if (this.put(next, { resourceType: type, resourceId: id, relation, subject }))
+                written++;
+        this.facts = next;
+        return { written, deleted };
+    }
+    list(resource) {
+        if (resource === null || resource === '')
+            throw invalid('`resource` is required', 'resource');
+        const { type, id } = parseResource(resource);
+        this.owned(type);
+        const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+        return { items: [...this.facts.values()].filter((f) => f.resourceType === type && f.resourceId === id)
+                .sort((a, b) => cmp(a.relation, b.relation) || cmp(a.subject.type, b.subject.type) || cmp(a.subject.id, b.subject.id)).map(factDto) };
+    }
+    /** The schema's permission over the facts, for the person `subject`: unknown types and permissions are false, as in the daemon. */
+    check(b) {
+        const subject = parseSubject(str(b['subject'], 'subject'));
+        const permission = str(b['permission'], 'permission');
+        const resource = parseResource(str(b['resource'], 'resource'));
+        if (subject.type !== 'user' || subject.relation !== '' || subject.id === '*')
+            throw invalid('`subject` must be `user:<id>`');
+        if (resource.type !== OBJECT_TYPE)
+            this.owned(resource.type);
+        return { allowed: holds(this.definitions(), this.facts.values(), subject.id, resource.type, resource.id, permission) };
+    }
+    write(b) {
+        const owner = b['owner'] === undefined || b['owner'] === 'app' ? 'app' : b['owner'] === 'user' ? 'user' : (() => { throw invalid('owner must be app or user', 'owner'); })();
+        const name = str(b['name'], 'name');
+        const schemaType = b['schema_type'] === undefined ? null : str(b['schema_type'], 'schema_type');
+        if (schemaType !== null)
+            this.owned(schemaType);
+        const relations = b['relations'] === undefined ? [] : this.factList(Array.isArray(b['relations']) ? b['relations'].map((r) => ({ resource: '', relation: r['relation'], subject: r['subject'] })) : b['relations'], 'relations');
+        if (relations.length > 0 && schemaType === null)
+            throw refuse(400, 'schema_type_required', 'relations need a schemaType: they are facts about a typed resource', { details: { field: 'relations' } });
+        if ([...this.docs.values()].some((d) => d.owner === owner && d.name === name))
+            throw refuse(409, 'name_taken', `${name} is already a document`);
+        const doc = {
+            id: `doc-${++this.serial}`, owner, name, body: str(b['body'], 'body'), preview: str(b['preview'], 'preview'),
+            summary: typeof b['summary'] === 'string' ? b['summary'] : null, kind: typeof b['kind'] === 'string' ? b['kind'] : 'knowledge', privacy: typeof b['privacy'] === 'string' ? b['privacy'] : 'public',
+            extensions: b['extensions'] === undefined ? {} : objectBody(b['extensions']), rules: Array.isArray(b['rules']) ? b['rules'] : [],
+            schemaType, revision: 1, createdAt: this.now(),
+        };
+        // A fact the schema refuses refuses the whole write: the document is not kept.
+        const next = new Map(this.facts);
+        for (const r of relations)
+            this.put(next, { resourceType: schemaType, resourceId: doc.id, relation: r.relation, subject: parseSubject(r.subject) });
+        this.facts = next;
+        this.docs.set(doc.id, doc);
+        return { id: doc.id, name: this.canonical(doc) };
+    }
+    edit(doc, b) {
+        str(b['rationale'], 'rationale');
+        if (b['body'] !== undefined && b['replace'] !== undefined)
+            throw invalid('pass body or replace, not both', 'replace');
+        if (b['body'] !== undefined)
+            doc.body = str(b['body'], 'body');
+        if (Array.isArray(b['replace'])) {
+            for (const r of b['replace']) {
+                const from = str(r['old'], 'old');
+                if (!doc.body.includes(from))
+                    throw refuse(409, 'replace_not_found', `${JSON.stringify(from)} is not in the document`);
+                doc.body = doc.body.replace(from, () => str(r['new'], 'new'));
+            }
+        }
+        for (const field of ['preview', 'summary', 'privacy'])
+            if (typeof b[field] === 'string')
+                doc[field] = b[field];
+        if (b['extensions'] !== undefined)
+            doc.extensions = objectBody(b['extensions']);
+        if (Array.isArray(b['rules']))
+            doc.rules = b['rules'];
+        if (Array.isArray(b['unset']))
+            for (const field of b['unset']) {
+                if (field === 'summary')
+                    doc.summary = null;
+                if (field === 'extensions')
+                    doc.extensions = {};
+                if (field === 'rules')
+                    doc.rules = [];
+            }
+        doc.revision++;
+        return { id: doc.id, name: this.canonical(doc), revision: doc.revision };
+    }
+    remove(doc) {
+        this.docs.delete(doc.id);
+        if (doc.schemaType !== null) {
+            for (const [key, f] of this.facts) {
+                const asResource = f.resourceType === doc.schemaType && f.resourceId === doc.id;
+                const asSubject = f.subject.type === doc.schemaType && f.subject.id === doc.id;
+                if (asResource || asSubject)
+                    this.facts.delete(key);
+            }
+        }
+        return { id: doc.id, name: this.canonical(doc) };
+    }
+    item(doc) {
+        return {
+            id: doc.id, type: 'document', kind: doc.kind, owner: { id: doc.owner === 'app' ? `app:${this.clientId}` : this.userId, type: doc.owner === 'app' ? 'app' : 'person', handle: this.ownerHandle(doc) },
+            privacy: doc.privacy, name: doc.name, preview: doc.preview, created_at: doc.createdAt, deleted_at: null,
+            schema_type: doc.schemaType, summary: doc.summary, rules: doc.rules.length, extensions: doc.extensions,
+        };
+    }
+    filter(name, schemaType, extensions, kind, limit, match) {
+        return [...this.docs.values()].reverse()
+            .filter((d) => (name === null || d.name.startsWith(name)) && (schemaType === null || d.schemaType === schemaType) && (kind === null || d.kind === kind)
+            && Object.entries(extensions ?? {}).every(([ns, fields]) => Object.entries(fields).every(([k, v]) => d.extensions[ns]?.[k] === v))
+            && (match === undefined || match(d)))
+            .slice(0, limit);
+    }
+    search(b) {
+        const text = str(b['text'], 'text').toLowerCase();
+        const grep = typeof b['grep'] === 'string' ? new RegExp(b['grep']) : null;
+        const extensions = b['extensions'] === undefined ? undefined : objectBody(b['extensions']);
+        const docs = this.filter(null, typeof b['schema_type'] === 'string' ? b['schema_type'] : null, extensions, typeof b['kind'] === 'string' ? b['kind'] : null, typeof b['limit'] === 'number' ? b['limit'] : 50, (d) => grep !== null ? d.body.split('\n').some((l) => grep.test(l)) : b['body'] === true ? d.body.toLowerCase().includes(text) : d.name.toLowerCase().includes(text));
+        return {
+            items: docs.map((d) => ({
+                object: this.item(d),
+                ...(grep !== null ? { matches: d.body.split('\n').flatMap((line, i) => (grep.test(line) ? [{ line: i + 1, text: line }] : [])) } : {}),
+            })),
+        };
+    }
+    read(doc) {
+        return {
+            state: 'object', type: 'document', object: this.item(doc), text: doc.body,
+            data: {
+                summary: doc.summary, revision: doc.revision, heads: [{ rev_id: `r${doc.revision}`, number: doc.revision, author_id: null, created_at: doc.createdAt }],
+                bodies: [doc.body], needs_merge: false, fields: { extensions: doc.extensions, rules: doc.rules },
+            },
+        };
+    }
+}

package/dist/testing/users.d.ts

@@ -1,5 +1,6 @@
 import type { GrantGetDTO, ProviderDependency, SetupState } from '@north-light/api';
 import type { FakeRun } from './run.js';
+import { FakeSpace } from './space.js';
 /** The directory's reasons for refusing a refresh token (the SDK's refusal table). */
 export type FakeRefusalCode = 'grant_removed' | 'grant_suspended' | 'app_in_testing' | 'refresh_token_expired' | 'refresh_token_reused' | 'grant_revoked' | 'runtime_provisioning';
 /** The identifiers a person's account holds. Only `email` (when `emailVerified`) and `phone` match a tester entry. */
@@ -29,7 +30,7 @@ export type FakeScope = string | {
 export interface FakeMemoryDoc {
     name: string;
     body: string;
-    privacy?: 'public' | 'friends' | 'private';
+    privacy?: 'public' | 'private';
     kind?: 'knowledge' | 'preference';
     created_at?: string;
     updated_at?: string;
@@ -76,6 +77,8 @@ export declare class UserState {
     responder: Responder | null;
     readonly memory: Map<string, StoredMemoryDoc>;
     readonly idempotency: Map<string, IdempotencyEntry>;
+    /** The app's documents, schemas and facts in this person's runtime. */
+    readonly space: FakeSpace;
     readonly holds: Set<Hold>;
     constructor(id: string, clientId: string, onRevoke: (user: UserState) => void, clock: {
         now(): number;

package/dist/testing/users.js

@@ -1,4 +1,5 @@
 import { IDEMPOTENCY_WINDOW_MS } from './conformance/keyed-write.js';
+import { FakeSpace } from './space.js';
 import { grantVersion, nowIso } from './wire.js';
 export const normalizeScopes = (scopes) => scopes.map((scope) => (typeof scope === 'string' ? { scope, mode: 'always' } : { scope: scope.scope, mode: scope.mode }));
 /** Internal per-user state. */
@@ -25,6 +26,8 @@ export class UserState {
     responder = null;
     memory = new Map();
     idempotency = new Map();
+    /** The app's documents, schemas and facts in this person's runtime. */
+    space;
     holds = new Set();
     constructor(id, clientId, onRevoke, clock) {
         this.id = id;
@@ -32,6 +35,7 @@ export class UserState {
         this.onRevoke = onRevoke;
         this.clock = clock;
         this.grantId = `grant-${id.replace(/^user:/, '')}`;
+        this.space = new FakeSpace(clientId, id, () => nowIso(this.clock.now()));
     }
     dto(exp = Math.floor(this.clock.now() / 1000) + 3600) {
         if (!this.active)

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export declare const SDK_VERSION = "0.3.548";
+export declare const SDK_VERSION = "0.3.550";
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the
  *  contract level existed (which only knows this header) refuses this SDK, while every later runtime accepts it. */
 export declare const LEGACY_FLOOR = "0.3.423";

package/dist/version.js

@@ -1,6 +1,6 @@
 // SDK_VERSION is written by scripts/release-version.mjs on every release; do not edit by hand.
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export const SDK_VERSION = '0.3.548';
+export const SDK_VERSION = '0.3.550';
 // LEGACY_FLOOR is written once by `scripts/contract.mjs release`, at the first release that carries the contract level
 // (the `0.0.0` placeholder is replaced there and never again); do not edit by hand.
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@north-light/sdk",
-  "version": "0.3.548",
-  "crouterContract": "1.30",
+  "version": "0.3.550",
+  "crouterContract": "1.31",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,9 +44,9 @@
     "prepublishOnly": "node -e \"if (process.env.npm_config_tag !== 'next') { console.error('@north-light/sdk publishes only with --tag next; scripts/promote-sdk.mjs is the only mover of latest.'); process.exit(1); }\""
   },
   "dependencies": {
-    "@north-light/api": "0.3.548",
-    "@north-light/identity": "0.3.548",
-    "@north-light/plugin": "0.3.548",
+    "@north-light/api": "0.3.550",
+    "@north-light/identity": "0.3.550",
+    "@north-light/plugin": "0.3.550",
     "jose": "^6.2.1"
   },
   "peerDependencies": {