@haverstack/commons 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+
+To the extent possible under law, the Haverstack contributors have waived all
+copyright and related or neighboring rights to Haverstack. This work is
+published from the United States.
+
+https://creativecommons.org/publicdomain/zero/1.0/

package/README.md

@@ -0,0 +1,59 @@
+# @haverstack/commons
+
+Canonical [Schema Commons](https://github.com/haverstack/core/tree/main/docs/commons)
+type definitions for Haverstack.
+
+The commons namespace `org.haverstack` is reserved for a small set of well-known,
+neutrally-governed types (`note`, `bookmark`, `task`, ...) so that apps sharing a stack
+can interoperate on the data shapes almost every personal app touches. That only works
+if every app registers a commons type **exactly as written** — a modified copy under
+the same `typeId` is schema drift, and the drift guard will (correctly) reject it. This
+package makes that structural rather than social: import the constant, don't
+hand-transcribe a schema out of markdown.
+
+> **Status:** Early development. Exports only Draft-status types — see
+> [`docs/commons/README.md`](https://github.com/haverstack/core/blob/main/docs/commons/README.md)
+> for what Draft/Staged/Proposed mean. Proposed types have no intended writer yet and
+> stay docs-only until they graduate.
+
+## Installation
+
+```sh
+npm install @haverstack/commons
+```
+
+## Usage
+
+```ts
+import { Stack } from '@haverstack/core';
+import { defineCommonsTypes, NOTE, TASK } from '@haverstack/commons';
+
+// Register only the commons types your app actually writes.
+await defineCommonsTypes(stack, [NOTE, TASK]);
+
+const note = await stack.create(NOTE.id, { text: 'Hello, Haverstack!' });
+```
+
+Each export (`NOTE`, `BOOKMARK`, `TASK`, `CONTACT`, `ARTICLE`, `PLACE`, `PAGE`, `PHOTO`)
+is a `{ id, name, schema }` triple mirroring its type's `stack.defineType(...)` block in
+[`docs/commons/`](https://github.com/haverstack/core/tree/main/docs/commons) exactly.
+`defineCommonsTypes()` is a thin loop over `stack.defineType()` — calling it again with
+types already registered is the ordinary idempotent no-op path (see `defineType`'s own
+docs), so it's safe to call on every app startup.
+
+## Governance
+
+The schemas here are not this package's to change. A type's shape, required core, and
+conventions are decided by the process in
+[`docs/commons/README.md` § Governance](https://github.com/haverstack/core/blob/main/docs/commons/README.md#governance) —
+propose additions or changes there, as an issue on `haverstack/core` titled
+`Commons: <proposal>`. This package's constants are updated to match once a proposal
+lands; it never carries a schema the docs don't also carry.
+
+## License
+
+[CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) — public domain.
+
+## Monorepo
+
+Part of [haverstack/core](https://github.com/haverstack/core).

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @haverstack/commons
+ * -------------------------------------------------------
+ * Canonical Schema Commons type definitions — see docs/commons/README.md for
+ * the design rules and governance process these schemas are bound by.
+ *
+ * Each export mirrors the fenced `stack.defineType(...)` block in its type's
+ * doc file exactly. Apps register commons types by passing these constants
+ * to `defineCommonsTypes()` rather than hand-copying schemas out of
+ * markdown, which is the drift the Schema Commons' governance process exists
+ * to prevent.
+ *
+ * Only Draft-status types are exported here. Proposed types (not yet backed
+ * by a concrete intended writer) stay docs-only until they graduate.
+ */
+import type { Stack, StackType, TypeId, TypeSchema } from '@haverstack/core';
+export type CommonsType = {
+    readonly id: TypeId;
+    readonly name: string;
+    readonly schema: TypeSchema;
+};
+export declare const NOTE: CommonsType;
+export declare const BOOKMARK: CommonsType;
+export declare const TASK: CommonsType;
+export declare const CONTACT: CommonsType;
+export declare const ARTICLE: CommonsType;
+export declare const PLACE: CommonsType;
+export declare const PAGE: CommonsType;
+export declare const PHOTO: CommonsType;
+/**
+ * Registers each given commons type on `stack` via `defineType()`, exactly
+ * as written here. Sequential, matching `Stack`'s own system-type seeding —
+ * each call is independent, but running in order keeps the returned array
+ * predictable.
+ */
+export declare const defineCommonsTypes: (stack: Stack, types: readonly CommonsType[]) => Promise<StackType[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE7E,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B,CAAC;AAUF,eAAO,MAAM,IAAI,EAAE,WAQlB,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,WAQtB,CAAC;AAEF,eAAO,MAAM,IAAI,EAAE,WAUlB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAWrB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAYrB,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,WAUnB,CAAC;AAEF,eAAO,MAAM,IAAI,EAAE,WAkBlB,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,WASnB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,KAAK,EACZ,OAAO,SAAS,WAAW,EAAE,KAC5B,OAAO,CAAC,SAAS,EAAE,CAMrB,CAAC"}

package/dist/index.js

@@ -0,0 +1,130 @@
+/**
+ * @haverstack/commons
+ * -------------------------------------------------------
+ * Canonical Schema Commons type definitions — see docs/commons/README.md for
+ * the design rules and governance process these schemas are bound by.
+ *
+ * Each export mirrors the fenced `stack.defineType(...)` block in its type's
+ * doc file exactly. Apps register commons types by passing these constants
+ * to `defineCommonsTypes()` rather than hand-copying schemas out of
+ * markdown, which is the drift the Schema Commons' governance process exists
+ * to prevent.
+ *
+ * Only Draft-status types are exported here. Proposed types (not yet backed
+ * by a concrete intended writer) stay docs-only until they graduate.
+ */
+const labeledValue = {
+    kind: 'object',
+    properties: {
+        value: { kind: 'string', required: true },
+        label: { kind: 'string' },
+    },
+};
+export const NOTE = {
+    id: 'org.haverstack/note@1',
+    name: 'Note',
+    schema: {
+        text: { kind: 'text', required: true },
+        title: { kind: 'string' },
+        format: { kind: 'string' },
+    },
+};
+export const BOOKMARK = {
+    id: 'org.haverstack/bookmark@1',
+    name: 'Bookmark',
+    schema: {
+        url: { kind: 'string', required: true },
+        title: { kind: 'string' },
+        description: { kind: 'text' },
+    },
+};
+export const TASK = {
+    id: 'org.haverstack/task@1',
+    name: 'Task',
+    schema: {
+        title: { kind: 'string', required: true },
+        done: { kind: 'boolean', required: true },
+        notes: { kind: 'text' },
+        due: { kind: 'date' },
+        completedAt: { kind: 'date' },
+    },
+};
+export const CONTACT = {
+    id: 'org.haverstack/contact@1',
+    name: 'Contact',
+    schema: {
+        name: { kind: 'string', required: true },
+        emails: { kind: 'array', items: labeledValue },
+        phones: { kind: 'array', items: labeledValue },
+        urls: { kind: 'array', items: labeledValue },
+        org: { kind: 'string' },
+        note: { kind: 'text' },
+    },
+};
+export const ARTICLE = {
+    id: 'org.haverstack/article@1',
+    name: 'Article',
+    schema: {
+        title: { kind: 'string', required: true },
+        text: { kind: 'text', required: true },
+        format: { kind: 'string' },
+        summary: { kind: 'text' },
+        url: { kind: 'string' },
+        author: { kind: 'string' },
+        publishedAt: { kind: 'date' },
+    },
+};
+export const PLACE = {
+    id: 'org.haverstack/place@1',
+    name: 'Place',
+    schema: {
+        latitude: { kind: 'number', required: true },
+        longitude: { kind: 'number', required: true },
+        name: { kind: 'string' },
+        address: { kind: 'string' },
+        url: { kind: 'string' },
+    },
+};
+export const PAGE = {
+    id: 'org.haverstack/page@1',
+    name: 'Page',
+    schema: {
+        slug: { kind: 'string', required: true },
+        text: { kind: 'text', required: true },
+        title: { kind: 'string' },
+        format: { kind: 'string' },
+        publishedAt: { kind: 'date' },
+        collection: {
+            kind: 'object',
+            properties: {
+                typeId: { kind: 'string', required: true },
+                tag: { kind: 'string' },
+                order: { kind: 'string' },
+            },
+        },
+    },
+};
+export const PHOTO = {
+    id: 'org.haverstack/photo@1',
+    name: 'Photo',
+    schema: {
+        image: { kind: 'file-ref', required: true },
+        caption: { kind: 'text' },
+        alt: { kind: 'string' },
+        takenAt: { kind: 'date' },
+    },
+};
+/**
+ * Registers each given commons type on `stack` via `defineType()`, exactly
+ * as written here. Sequential, matching `Stack`'s own system-type seeding —
+ * each call is independent, but running in order keeps the returned array
+ * predictable.
+ */
+export const defineCommonsTypes = async (stack, types) => {
+    const defined = [];
+    for (const type of types) {
+        defined.push(await stack.defineType(type.id, type.name, type.schema));
+    }
+    return defined;
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@haverstack/commons",
+  "version": "0.1.0",
+  "description": "Canonical Schema Commons type definitions for Haverstack — register commons types exactly as written",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/haverstack/core",
+    "directory": "packages/commons"
+  },
+  "license": "CC0-1.0",
+  "keywords": [
+    "haverstack",
+    "personal data",
+    "schema commons",
+    "interop"
+  ],
+  "dependencies": {
+    "@haverstack/core": "^0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests"
+  }
+}