@absolutejs/artifacts 0.0.1

package/LICENSE

@@ -0,0 +1,90 @@
+# Business Source License 1.1
+
+**Licensor:** Alex Kahn
+
+**Licensed Work:** @absolutejs/artifacts (https://github.com/absolutejs/artifacts)
+
+**Change Date:** July 14, 2030
+
+**Change License:** Apache License, Version 2.0
+
+---
+
+## Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, permitting limited production use.
+
+### Additional Use Grant
+
+You may use the Licensed Work in production, provided your use does not include
+any of the following:
+
+1. **Offering a Competing Service.** You may not offer the Licensed Work, or
+   any derivative or substantial portion of it, to third parties as a hosted or
+   managed AI artifact-generation, document/page-creation, editing, rendering,
+   publishing, or artifact-management service (including, but not limited to,
+   services like Canva, Gamma, Adobe Express, Notion AI, Webflow AI, or v0).
+   This includes any product whose primary value to its users is the
+   functionality the Licensed Work provides.
+
+2. **Resale or Redistribution as a Standalone Product.** You may not sell,
+   license, or distribute the Licensed Work, or any derivative or fork of it,
+   as a standalone commercial product.
+
+3. **Removal of Attribution.** Any derivative work, fork, or redistribution of
+   the Licensed Work must prominently credit AbsoluteJS and include a link to
+   the original project repository (https://github.com/absolutejs/artifacts).
+
+For clarity, the following uses are expressly permitted:
+
+- Using the Licensed Work to build and operate your own applications, websites,
+  internal tools, or SaaS products (whether commercial or non-commercial), so
+  long as the Licensed Work itself is not the primary product you are selling.
+- Using the Licensed Work as a dependency in commercial software you build and
+  sell, as long as the software is not itself a competing managed service of
+  the kind described in clause 1.
+- Providing consulting, development, or professional services to clients using
+  the Licensed Work.
+- Forking and modifying the Licensed Work for your own internal use, provided
+  attribution is maintained.
+
+### Change Date and Change License
+
+On the Change Date specified above, or on such other date as the Licensor may
+specify by written notice, the Licensed Work will be made available under the
+Change License (Apache License, Version 2.0). Until the Change Date, the terms
+of this Business Source License 1.1 apply.
+
+### Trademark
+
+This license does not grant you any rights to use the "AbsoluteJS" or
+"@absolutejs" name, logo, or any related trademarks. Forks and derivative works
+must not be named or branded in a manner that suggests endorsement by or
+affiliation with AbsoluteJS or the Licensor.
+
+### Notices
+
+You must not remove or obscure any licensing, copyright, or other notices
+included in the Licensed Work.
+
+### No Warranty
+
+THE LICENSED WORK IS PROVIDED "AS IS". THE LICENSOR HEREBY DISCLAIMS ALL
+WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR
+IN CONNECTION WITH THE LICENSED WORK OR THE USE OR OTHER DEALINGS IN THE
+LICENSED WORK.
+
+---
+
+## Contact
+
+For commercial licensing inquiries or additional permissions, contact:
+
+- **Alex Kahn**
+- alexkahndev@gmail.com
+- alexkahndev.github.io

package/README.md

@@ -0,0 +1,128 @@
+# @absolutejs/artifacts
+
+The typed lifecycle for things an AI makes.
+
+An AI-generated page, report, plan, email, deck, or image should not disappear
+into a chat transcript or become an unvalidated blob. It should have a kind,
+structured content, ownership, provenance, revisions, capabilities, renderers,
+and an explicit publication lifecycle.
+
+`@absolutejs/artifacts` provides those contracts without owning your database,
+routes, authorization, UI, or hosting.
+
+## What it owns
+
+- Structured artifact-kind schemas and runtime validation
+- Draft, published, and archived lifecycle states
+- Optimistic revisions that prevent lost edits
+- Storage, renderer, and publisher interfaces
+- An in-memory store for development and tests
+- Owner-bound lifecycle tools structurally compatible with AI tool maps
+- Provenance fields for model, tool, trace, and source entities
+
+Your application retains authorization, durable persistence, public tokens,
+URLs, notifications, analytics, submissions, and product-specific rendering.
+
+## Define kinds once
+
+```ts
+import { Type } from "@sinclair/typebox";
+import {
+  createArtifactService,
+  createMemoryArtifactStore,
+  defineArtifactRegistry,
+} from "@absolutejs/artifacts";
+
+const registry = defineArtifactRegistry({
+  page: {
+    capabilities: ["archive", "edit", "preview", "publish"],
+    content: Type.Object({
+      blocks: Type.Array(
+        Type.Union([
+          Type.Object({ heading: Type.String(), type: Type.Literal("hero") }),
+          Type.Object({ body: Type.String(), type: Type.Literal("text") }),
+        ]),
+      ),
+      theme: Type.Union([Type.Literal("dark"), Type.Literal("light")]),
+    }),
+    label: "Page",
+    schemaVersion: 1,
+  },
+});
+
+const artifacts = createArtifactService({
+  registry,
+  store: createMemoryArtifactStore(),
+});
+
+const page = await artifacts.create("owner-123", {
+  content: {
+    blocks: [{ heading: "A real page", type: "hero" }],
+    theme: "light",
+  },
+  createdBy: "agent",
+  kind: "page",
+  provenance: { model: "your-model", tool: "create_page" },
+  title: "Launch page",
+});
+```
+
+## Compose publishing and rendering
+
+Publishing is an adapter because public access is a host policy:
+
+```ts
+const artifacts = createArtifactService({
+  publisher: {
+    publish: async (artifact, { idempotencyKey }) =>
+      mintPublicTokenAndUrl(artifact, idempotencyKey),
+    unpublish: async (artifact, { idempotencyKey }) =>
+      revokePublicAccess(artifact, idempotencyKey),
+  },
+  registry,
+  store: postgresArtifactStore,
+});
+```
+
+Renderers are independently registered by artifact kind and output format:
+
+```ts
+const renderers = createArtifactRendererRegistry([
+  {
+    format: "html",
+    kind: "page",
+    render: async (artifact) => ({
+      body: renderSafePage(artifact.content),
+      mediaType: "text/html; charset=utf-8",
+    }),
+  },
+]);
+```
+
+The package never treats generated HTML or JavaScript as trusted executable
+content. Applications should define structured content schemas and render them
+through controlled adapters.
+
+## AI tools
+
+`createArtifactTools` binds create, list, get, update, publish, and unpublish
+operations to one owner. The returned definitions use TypeBox inputs and the
+same `{ description, input, handler }` shape used by `@absolutejs/ai`.
+
+```ts
+const tools = createArtifactTools({
+  createdBy: "agent",
+  ownerId: member.id,
+  service: artifacts,
+});
+```
+
+Only expose the publication tool where the user explicitly controls public
+access.
+
+## License
+
+Business Source License 1.1 — free for your own products, applications, and
+internal use; you may not offer it as a competing hosted AI artifact-generation,
+editing, rendering, publishing, or artifact-management service. Converts to
+Apache 2.0 on July 14, 2030. See [LICENSE](./LICENSE).

package/dist/index.js

@@ -0,0 +1,296 @@
+// @bun
+// src/registry.ts
+import { Value } from "@sinclair/typebox/value";
+
+// src/types.ts
+var ARTIFACT_STATUSES = ["draft", "published", "archived"];
+
+class ArtifactError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ArtifactError";
+    this.code = code;
+  }
+}
+
+// src/registry.ts
+var defineArtifactRegistry = (definitions) => ({
+  definitions,
+  kindNames: Object.keys(definitions),
+  parse: (kind, content) => {
+    const definition = definitions[kind];
+    if (!definition) {
+      throw new ArtifactError("unknown_kind", `Unknown artifact kind: ${kind}`);
+    }
+    if (!Value.Check(definition.content, content)) {
+      const issue = [...Value.Errors(definition.content, content)][0];
+      const detail = issue ? `${issue.path || "/"}: ${issue.message}` : "invalid content";
+      throw new ArtifactError("invalid_content", `Invalid ${kind} artifact content (${detail})`);
+    }
+    return content;
+  }
+});
+// src/renderers.ts
+var createArtifactRendererRegistry = (initial = []) => {
+  const key = (kind, format) => `${kind}:${format}`;
+  const renderers = new Map(initial.map((renderer) => [key(renderer.kind, renderer.format), renderer]));
+  return {
+    formatsFor: (kind) => [...renderers.values()].filter((renderer) => renderer.kind === kind).map((renderer) => renderer.format),
+    register: (renderer) => {
+      renderers.set(key(renderer.kind, renderer.format), renderer);
+    },
+    render: async (artifact, format) => {
+      const renderer = renderers.get(key(artifact.kind, format));
+      if (!renderer) {
+        throw new ArtifactError("renderer_unavailable", `No ${format} renderer is registered for ${artifact.kind}`);
+      }
+      return renderer.render(artifact);
+    }
+  };
+};
+// src/service.ts
+var requireCapability = (artifact, capability) => {
+  if (!artifact.capabilities.includes(capability)) {
+    throw new ArtifactError("unsupported_capability", `${artifact.kind} artifacts do not support ${capability}`);
+  }
+};
+var createArtifactService = (options) => {
+  const now = () => (options.clock ?? (() => new Date))().toISOString();
+  const idFactory = options.idFactory ?? (() => crypto.randomUUID());
+  const get = async (ownerId, artifactId) => {
+    const artifact = await options.store.get(ownerId, artifactId);
+    if (!artifact) {
+      throw new ArtifactError("not_found", "Artifact not found");
+    }
+    return artifact;
+  };
+  const saveRevision = async (artifact, expectedRevision) => {
+    const saved = await options.store.save(artifact, expectedRevision);
+    if (!saved) {
+      throw new ArtifactError("conflict", "Artifact changed since it was opened; reload before saving");
+    }
+    return artifact;
+  };
+  return {
+    archive: async (ownerId, artifactId) => {
+      const current = await get(ownerId, artifactId);
+      requireCapability(current, "archive");
+      return saveRevision({
+        ...current,
+        revision: current.revision + 1,
+        status: "archived",
+        updatedAt: now()
+      }, current.revision);
+    },
+    create: async (ownerId, input) => {
+      const definition = options.registry.definitions[input.kind];
+      if (!definition) {
+        throw new ArtifactError("unknown_kind", `Unknown artifact kind: ${input.kind}`);
+      }
+      const content = options.registry.parse(input.kind, input.content);
+      const timestamp = now();
+      const artifact = {
+        capabilities: definition.capabilities ?? ["archive", "edit", "preview"],
+        content,
+        createdAt: timestamp,
+        createdBy: input.createdBy,
+        id: idFactory(),
+        kind: input.kind,
+        metadata: input.metadata ?? {},
+        ownerId,
+        provenance: input.provenance,
+        revision: 1,
+        schemaVersion: definition.schemaVersion ?? 1,
+        status: "draft",
+        title: input.title.trim(),
+        updatedAt: timestamp
+      };
+      await options.store.create(artifact);
+      return artifact;
+    },
+    get,
+    list: (ownerId, query) => options.store.list(ownerId, query),
+    publish: async (ownerId, artifactId) => {
+      const current = await get(ownerId, artifactId);
+      requireCapability(current, "publish");
+      if (!options.publisher) {
+        throw new ArtifactError("publisher_unavailable", "No artifact publisher is configured");
+      }
+      const result = await options.publisher.publish(current, {
+        idempotencyKey: `artifact:${current.id}:publish:${current.revision + 1}`
+      });
+      const publishedAt = now();
+      const publication = {
+        id: result.id,
+        publishedAt,
+        url: result.url
+      };
+      return saveRevision({
+        ...current,
+        publication,
+        revision: current.revision + 1,
+        status: "published",
+        updatedAt: publishedAt
+      }, current.revision);
+    },
+    unpublish: async (ownerId, artifactId) => {
+      const current = await get(ownerId, artifactId);
+      requireCapability(current, "publish");
+      if (!options.publisher) {
+        throw new ArtifactError("publisher_unavailable", "No artifact publisher is configured");
+      }
+      await options.publisher.unpublish(current, {
+        idempotencyKey: `artifact:${current.id}:unpublish:${current.revision + 1}`
+      });
+      return saveRevision({
+        ...current,
+        publication: undefined,
+        revision: current.revision + 1,
+        status: "draft",
+        updatedAt: now()
+      }, current.revision);
+    },
+    update: async (ownerId, artifactId, input) => {
+      const current = await get(ownerId, artifactId);
+      requireCapability(current, "edit");
+      const expectedRevision = input.expectedRevision ?? current.revision;
+      const content = input.content === undefined ? current.content : options.registry.parse(current.kind, input.content);
+      return saveRevision({
+        ...current,
+        content,
+        metadata: input.metadata ?? current.metadata,
+        revision: current.revision + 1,
+        title: input.title?.trim() || current.title,
+        updatedAt: now()
+      }, expectedRevision);
+    }
+  };
+};
+// src/store.ts
+var clone = (value) => structuredClone(value);
+var createMemoryArtifactStore = (initial = []) => {
+  const records = new Map(initial.map((record) => [record.id, clone(record)]));
+  return {
+    create: async (record) => {
+      if (records.has(record.id))
+        throw new Error(`Duplicate artifact id: ${record.id}`);
+      records.set(record.id, clone(record));
+    },
+    get: async (ownerId, artifactId) => {
+      const record = records.get(artifactId);
+      return record?.ownerId === ownerId ? clone(record) : null;
+    },
+    list: async (ownerId, query = {}) => [...records.values()].filter((record) => record.ownerId === ownerId && (!query.kind || record.kind === query.kind) && (!query.status || record.status === query.status)).sort((left, right) => right.updatedAt.localeCompare(left.updatedAt)).slice(0, query.limit ?? Number.POSITIVE_INFINITY).map(clone),
+    save: async (record, expectedRevision) => {
+      const current = records.get(record.id);
+      if (!current || current.ownerId !== record.ownerId || current.revision !== expectedRevision) {
+        return false;
+      }
+      records.set(record.id, clone(record));
+      return true;
+    }
+  };
+};
+// src/tools.ts
+import { Type } from "@sinclair/typebox";
+var record = (input) => input && typeof input === "object" && !Array.isArray(input) ? input : {};
+var stringValue = (input, key) => typeof input[key] === "string" ? input[key] : undefined;
+var createArtifactTools = (options) => ({
+  artifact_create: {
+    description: "Create a private, typed artifact. The kind must be registered by the host; publishing is a separate explicit action.",
+    handler: async (raw) => {
+      const input = record(raw);
+      const kind = stringValue(input, "kind");
+      const title = stringValue(input, "title");
+      if (!kind || !title || input.content === undefined) {
+        return "Provide kind, title, and content.";
+      }
+      const artifact = await options.service.create(options.ownerId, {
+        content: input.content,
+        createdBy: options.createdBy,
+        kind,
+        title
+      });
+      return JSON.stringify(artifact);
+    },
+    input: Type.Object({
+      content: Type.Unknown(),
+      kind: Type.String({ minLength: 1 }),
+      title: Type.String({ minLength: 1 })
+    })
+  },
+  artifact_get: {
+    annotations: { readOnlyHint: true },
+    description: "Open one artifact owned by the current user.",
+    handler: async (raw) => {
+      const artifactId = stringValue(record(raw), "artifactId");
+      if (!artifactId)
+        return "Provide artifactId.";
+      return JSON.stringify(await options.service.get(options.ownerId, artifactId));
+    },
+    input: Type.Object({ artifactId: Type.String({ minLength: 1 }) })
+  },
+  artifact_list: {
+    annotations: { readOnlyHint: true },
+    description: "List artifacts owned by the current user.",
+    handler: async (raw) => {
+      const input = record(raw);
+      const status = stringValue(input, "status");
+      return JSON.stringify(await options.service.list(options.ownerId, {
+        kind: stringValue(input, "kind"),
+        status: ARTIFACT_STATUSES.find((candidate) => candidate === status)
+      }));
+    },
+    input: Type.Object({
+      kind: Type.Optional(Type.String()),
+      status: Type.Optional(Type.Union(ARTIFACT_STATUSES.map((status) => Type.Literal(status))))
+    })
+  },
+  artifact_publish: {
+    description: "Publish or unpublish an artifact. Hosts should expose this tool only when the user explicitly controls public access.",
+    handler: async (raw) => {
+      const input = record(raw);
+      const artifactId = stringValue(input, "artifactId");
+      if (!artifactId || typeof input.published !== "boolean") {
+        return "Provide artifactId and published.";
+      }
+      const artifact = input.published ? await options.service.publish(options.ownerId, artifactId) : await options.service.unpublish(options.ownerId, artifactId);
+      return JSON.stringify(artifact);
+    },
+    input: Type.Object({
+      artifactId: Type.String({ minLength: 1 }),
+      published: Type.Boolean()
+    })
+  },
+  artifact_update: {
+    description: "Update an artifact's title or structured content with optional optimistic revision protection.",
+    handler: async (raw) => {
+      const input = record(raw);
+      const artifactId = stringValue(input, "artifactId");
+      if (!artifactId)
+        return "Provide artifactId.";
+      const artifact = await options.service.update(options.ownerId, artifactId, {
+        content: input.content,
+        expectedRevision: typeof input.expectedRevision === "number" ? input.expectedRevision : undefined,
+        title: stringValue(input, "title")
+      });
+      return JSON.stringify(artifact);
+    },
+    input: Type.Object({
+      artifactId: Type.String({ minLength: 1 }),
+      content: Type.Optional(Type.Unknown()),
+      expectedRevision: Type.Optional(Type.Integer({ minimum: 1 })),
+      title: Type.Optional(Type.String({ minLength: 1 }))
+    })
+  }
+});
+export {
+  defineArtifactRegistry,
+  createMemoryArtifactStore,
+  createArtifactTools,
+  createArtifactService,
+  createArtifactRendererRegistry,
+  ArtifactError,
+  ARTIFACT_STATUSES
+};