@north-light/api 0.3.549 → 0.3.551

package/dist/api/contract.d.ts

@@ -1,5 +1,5 @@
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export declare const CONTRACT_LEVEL = "1.30";
+export declare const CONTRACT_LEVEL = "1.31";
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export declare const REQUIRED_CONTRACT_HEADER = "Crouter-Required-Contract";
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/contract.js

@@ -12,7 +12,7 @@
 //
 // PURITY (spec §3.1): Node built-ins + `src/api/*` only.
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export const CONTRACT_LEVEL = '1.30';
+export const CONTRACT_LEVEL = '1.31';
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export const REQUIRED_CONTRACT_HEADER = 'Crouter-Required-Contract';
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/dto/custom-objects.d.ts

@@ -19,7 +19,7 @@ export interface RegisterCustomObjectRequestDTO {
     events?: Record<string, CustomEventSpecDTO>;
     receiver?: CustomReceiverDTO;
     rotate_token?: boolean;
-    /** Who can read the instance: `public` (default), `friends` or `private`. Setting it on an existing instance changes it. */
+    /** Who can read the instance: `public` (default) or `private`. Setting it on an existing instance changes it. */
     privacy?: PrivacyName;
 }
 export interface RegisterCustomObjectResponseDTO {

package/dist/api/dto/docs.d.ts

@@ -27,9 +27,17 @@ export interface DocWriteRequest {
     unlisted?: boolean;
     lint_ignore?: string[];
     extensions?: Record<string, Record<string, unknown>>;
+    /** The app type the document is an instance of (`firstlight/memory`), in the calling app's own namespace. The app's schema then governs who reads it. */
+    schema_type?: string;
+    /** Facts written in the same transaction as the document, with resource `<schema_type>:<new object id>`. Subject: `user:<id>`, `<type>:<id>` or `<type>:<id>#<relation>`. */
+    relations?: DocRelationDTO[];
     /** The caller's cwd, for `--owner repo` resolution. */
     cwd?: string;
 }
+export interface DocRelationDTO {
+    relation: string;
+    subject: string;
+}
 /** `name` is canonical: `<owner-handle>/<name>`. */
 /** `unresolved_links`: names that match nothing in the writer's view. `remote_links`: names whose
  *  first segment is no owner on this runtime — on another runtime, or misspelled. */
@@ -99,6 +107,10 @@ export interface DocRevisionDTO {
     verbatim: boolean;
     created_at: string;
     parents: string[];
+    /** The app that made the revision (`app:firstlight`), or null. */
+    acting_app: string | null;
+    /** The person the revision was made for (`user:<id>`), or null. */
+    acting_for: string | null;
 }
 export interface DocHistoryDTO {
     object: ObjectDTO;

package/dist/api/dto/objects.d.ts

@@ -1,4 +1,4 @@
-export declare const PRIVACY_LEVELS_DTO: readonly ["public", "friends", "private"];
+export declare const PRIVACY_LEVELS_DTO: readonly ["public", "private"];
 export type PrivacyName = typeof PRIVACY_LEVELS_DTO[number];
 export type OwnerTypeName = 'person' | 'app' | 'repo' | 'profile' | 'node' | 'document' | 'job';
 export interface ObjectOwnerDTO {
@@ -34,6 +34,8 @@ export interface ObjectDTO {
     preview: string;
     created_at: string;
     deleted_at: string | null;
+    /** The app type a document is an instance of (`firstlight/memory`); null for a document governed by `crtr/object`. Present on documents. */
+    schema_type?: string | null;
     /** Present on an instance of a custom kind. */
     kind_decl?: ObjectKindDeclDTO;
 }
@@ -141,6 +143,12 @@ export interface ObjectListRequest {
     cursor?: string;
     /** List only this machine (`runtime:<id>`), paging through its cursor. `self` lists only this machine without labels. */
     machine?: string;
+    /** Documents whose `extensions` hold these top-level fields (equality), e.g. `{ firstlight: { workspace_id: 'w1', state: 'active' } }`. Applied inside the permission-filtered query, before `limit`. */
+    extensions?: Record<string, Record<string, unknown>>;
+    /** Documents that are instances of this app type (`firstlight/memory`). */
+    schema_type?: string;
+    /** Only objects the caller reaches through a share and not through its own tree. */
+    shared?: boolean;
 }
 export interface ObjectListItemDTO extends ObjectDTO {
     /** The machine of your account that homes the row; set on a merged or `--machine` listing. */
@@ -148,6 +156,10 @@ export interface ObjectListItemDTO extends ObjectDTO {
     summary?: string | null;
     /** A document's rule count. */
     rules?: number;
+    /** A document's `extensions`, as stored. Present on document items. */
+    extensions?: Record<string, Record<string, unknown>>;
+    /** A document's app type, or null. Present on document items. */
+    schema_type?: string | null;
 }
 export type MachineListState = 'ok' | 'unreachable' | 'too_old';
 /** How one machine answered a merged listing; `more` says its first page was not all of it (page it with `--machine`). */
@@ -172,7 +184,11 @@ export interface ObjectSearchRequest {
     kind?: string;
     owner?: string;
     limit?: number;
+    /** As on `ObjectListRequest`: applied inside the query in every search mode (name, `body`, `grep`). */
+    extensions?: Record<string, Record<string, unknown>>;
+    schema_type?: string;
 }
+/** `object` is an `ObjectListItemDTO`, so a document hit carries its `extensions` and `schema_type` there. */
 export interface ObjectSearchHitDTO {
     object: ObjectListItemDTO;
     matches?: Array<{

package/dist/api/dto/objects.js

@@ -2,4 +2,4 @@
 // watch, unwatch, edges) over documents, nodes, jobs and owners.
 //
 // PURITY (spec §3.1): Node built-ins + `src/api/*` only.
-export const PRIVACY_LEVELS_DTO = ['public', 'friends', 'private'];
+export const PRIVACY_LEVELS_DTO = ['public', 'private'];

package/dist/api/dto/permissions.d.ts

@@ -0,0 +1,76 @@
+/** `POST /v1/schemas`: register or update the calling app's permission schema (SpiceDB syntax). */
+export interface SchemaRegisterRequest {
+    namespace: string;
+    source: string;
+}
+export interface SchemaRegisterDTO {
+    namespace: string;
+    version: number;
+    changed: boolean;
+}
+/** One relation fact. `resource` is `<type>:<id>` within the caller's namespace; `subject` is `user:<id>`, `<type>:<id>` or `<type>:<id>#<relation>`. */
+export interface FactDTO {
+    resource: string;
+    relation: string;
+    subject: string;
+}
+/** `POST /v1/relations`: idempotent writes and deletes of facts. */
+export interface RelationsWriteRequest {
+    write?: FactDTO[];
+    delete?: FactDTO[];
+}
+/** `PUT /v1/relations`: the facts `(resource, relation, *)` become exactly `subjects`. */
+export interface RelationsReplaceRequest {
+    resource: string;
+    relation: string;
+    subjects: string[];
+}
+export interface RelationsChangedDTO {
+    written: number;
+    deleted: number;
+}
+/** `GET /v1/relations?resource=<type>:<id>`. */
+export interface RelationsListDTO {
+    items: FactDTO[];
+}
+/** `POST /v1/check`: may `subject` do `permission` on `resource` (`<type>:<id>`, or a crouter object id with `read|edit|message|use`). */
+export interface CheckRequest {
+    subject: string;
+    permission: string;
+    resource: string;
+}
+export interface CheckDTO {
+    allowed: boolean;
+}
+/** The CLI verbs of a share and the relation each writes on a `crtr/object`. */
+export declare const SHARE_VERBS: readonly ["read", "edit", "message", "use"];
+export type ShareVerb = typeof SHARE_VERBS[number];
+/** `POST /v1/objects/:ref/shares`: share the object. `subject` is `user:<id>`, `team:<id>` or `user:*` (everyone). */
+export interface ShareRequest {
+    verb: ShareVerb;
+    subject: string;
+}
+/** `DELETE /v1/objects/:ref/shares?verb=&subject=`: revoke it. Same pair as the request. */
+export interface ShareRevokeQuery {
+    verb: ShareVerb;
+    subject: string;
+}
+/** The object and fact a share call acted on; `changed` is false when the fact already held (or was already absent). */
+export interface ShareChangedDTO {
+    id: string;
+    name: string;
+    relation: string;
+    subject: string;
+    changed: boolean;
+}
+/** `GET /v1/objects/:ref/shares`: who the object is shared with, for those who may share it. */
+export interface ShareListDTO {
+    id: string;
+    name: string;
+    items: Array<{
+        verb: ShareVerb;
+        subject: string;
+        written_by: string;
+        created_at: string;
+    }>;
+}

package/dist/api/dto/permissions.js

@@ -0,0 +1,5 @@
+// Permission DTOs — `POST /v1/schemas`, `/v1/relations` and `POST /v1/check`.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+/** The CLI verbs of a share and the relation each writes on a `crtr/object`. */
+export const SHARE_VERBS = ['read', 'edit', 'message', 'use'];

package/dist/api/index.d.ts

@@ -49,5 +49,6 @@ export * from './dto/chat-inventory.js';
 export * from './dto/analytics.js';
 export * from './dto/custom-objects.js';
 export * from './dto/plugins.js';
-export type { DeliveryRuleDTO, DocEditRequest, DocEditedDTO, DocKindName, DocUnsetField, DocWriteRequest, DocWrittenDTO, DocLinkReportDTO, DocStaleDTO, RuleDeliverName, RuleOnName, } from './dto/docs.js';
-export type { DocumentReadData, ObjectDTO, ObjectReadDTO, WatchRequest, WatchResultDTO, UnwatchQuery, UnwatchResultDTO } from './dto/objects.js';
+export * from './dto/permissions.js';
+export type { DeliveryRuleDTO, DocDeletedDTO, DocHistoryDTO, DocRelationDTO, DocRevisionDTO, DocEditRequest, DocEditedDTO, DocKindName, DocUnsetField, DocWriteRequest, DocWrittenDTO, DocLinkReportDTO, DocStaleDTO, RuleDeliverName, RuleOnName, } from './dto/docs.js';
+export type { DocumentReadData, ObjectDTO, ObjectListDTO, ObjectListItemDTO, ObjectListRequest, ObjectSearchDTO, ObjectSearchHitDTO, ObjectSearchRequest, ObjectReadDTO, WatchRequest, WatchResultDTO, UnwatchQuery, UnwatchResultDTO } from './dto/objects.js';

package/dist/api/index.js

@@ -46,3 +46,4 @@ export * from './dto/chat-inventory.js';
 export * from './dto/analytics.js';
 export * from './dto/custom-objects.js';
 export * from './dto/plugins.js';
+export * from './dto/permissions.js';

package/dist/api/routes.d.ts

@@ -157,12 +157,16 @@ export declare const routes: {
     readonly customObjectEvents: (ref: string) => string;
     readonly customObjectDeliveries: (ref: string) => string;
     readonly customObjectAck: (ref: string) => string;
+    readonly objectShares: (ref: string) => string;
     readonly objectEdges: (ref: string) => string;
     readonly docs: () => string;
     readonly doc: (ref: string) => string;
     readonly docMove: (ref: string) => string;
     readonly docHistory: (ref: string) => string;
     readonly docsLint: () => string;
+    readonly schemas: () => string;
+    readonly relations: () => string;
+    readonly check: () => string;
     readonly pluginAppToken: (name: string) => string;
     readonly pluginCallHeaders: (name: string) => string;
     readonly documentsBrowserAccess: () => string;

package/dist/api/routes.js

@@ -190,12 +190,16 @@ export const routes = {
     customObjectEvents: (ref) => `${V}/custom-objects/${encodeURIComponent(ref)}/events`,
     customObjectDeliveries: (ref) => `${V}/custom-objects/${encodeURIComponent(ref)}/deliveries`,
     customObjectAck: (ref) => `${V}/custom-objects/${encodeURIComponent(ref)}/deliveries/ack`,
+    objectShares: (ref) => `${V}/objects/${encodeURIComponent(ref)}/shares`,
     objectEdges: (ref) => `${V}/objects/${encodeURIComponent(ref)}/edges`,
     docs: () => `${V}/docs`,
     doc: (ref) => `${V}/docs/${encodeURIComponent(ref)}`,
     docMove: (ref) => `${V}/docs/${encodeURIComponent(ref)}/move`,
     docHistory: (ref) => `${V}/docs/${encodeURIComponent(ref)}/history`,
     docsLint: () => `${V}/docs/lint`,
+    schemas: () => `${V}/schemas`,
+    relations: () => `${V}/relations`,
+    check: () => `${V}/check`,
     pluginAppToken: (name) => `${V}/plugins/${encodeURIComponent(name)}/app-token`,
     pluginCallHeaders: (name) => `${V}/plugins/${encodeURIComponent(name)}/call-headers`,
     documentsBrowserAccess: () => `${V}/documents/browser-access`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.549",
+  "version": "0.3.551",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",