anbaric 1.54.0 → 1.56.0

package/docs/README.md

@@ -25,6 +25,7 @@ What the framework gives you, one capability at a time.
 - [AI agents](features/ai-agents.md) — letting a model drive a state
 - [Documents and secrets](features/documents-and-secrets.md) — the JSON and secret stores
 - [The SQL store](features/sql-store.md) — a relational database for structured data
+- [File storage](features/file-storage.md) — bytes at a path, local or in your tenant's storage
 - [Auditing](features/auditing.md) — the record of who changed what
 - [Entitlements](features/entitlements.md) — what a user has been granted, checked per request
 - [Prompts](features/prompts.md) — versioned model instructions and schemas, saved at startup
@@ -52,7 +53,7 @@ The surface you build against.
 - [TypeScript API](api/typescript.md) — the full app-facing library
   - [State machines](api/state-machine.md) — `StateMachine`, `State`, `Action`, `Await`, `Transition`, `Job`, `PropertyDefinition`
   - [Actors and agents](api/actors-and-agents.md) — `Code`, `Human`, `Agent`, AI actions
-  - [Stores](api/stores.md) — `JsonStore`, `SecretStore`, `SqlStore` and their factories
+  - [Stores](api/stores.md) — `JsonStore`, `SecretStore`, `SqlStore`, `FileStorage` and their factories
   - [Environment and factories](api/environment.md) — the `ANBARIC_*` variables
 - [Web APIs](api/web.md) — serving HTTP, the app proxy, and the platform endpoints you call
 - [CLI reference](api/cli.md) — the `anbaric` command

package/docs/api/environment.md

@@ -33,6 +33,7 @@ defaulting to a local implementation otherwise).
 | `ANBARIC_AUDITOR_TYPE` | the audit sink (`cloud` → platform) | console |
 | `ANBARIC_JSON_STORE_TYPE` | the JSON document store | in-memory |
 | `ANBARIC_SECRET_STORE_TYPE` | the secret store | in-memory (encrypted) |
+| `ANBARIC_FILE_STORAGE_TYPE` | the [file storage](../features/file-storage.md) | local disk |
 | `ANBARIC_SQL_STORE_TYPE` | the SQL store (`sqlite` / `cloud`\|`postgres`) | SQLite |
 | `ANBARIC_SESSION_RESOLVER_TYPE` | how `Human.fromSession` resolves sessions | in-memory |
 | `ANBARIC_ENTITLEMENTS_TYPE` | how `hasEntitlement` is answered (`cloud` → platform) | permissive (always `true`) |
@@ -47,6 +48,7 @@ Used by the store implementations the factories return:
 | `ANBARIC_SQL_FILE` | SQLite | file path to persist to (default `:memory:`) |
 | `ANBARIC_SQL_DATABASE_URL` | PostgreSQL | connection string |
 | `ANBARIC_SQL_SCHEMA` | PostgreSQL | schema name (default `anbaric_app_data`) |
+| `ANBARIC_FILE_STORAGE_PATH` | local file storage | directory to keep files in (default `<temp dir>/anbaric/files`) |
 
 ## Platform-injected variables
 

package/docs/api/stores.md

@@ -86,6 +86,37 @@ const key = await secrets.retrieve("stripe-key", actor);
 
 ---
 
+## `FileStorage`
+
+Bytes at a path, with a content type. `list` returns metadata only.
+
+```ts
+FileStorageFactory.instance() : FileStorage
+
+// methods:
+put(actor : Actor, path : string, contents : Uint8Array, contentType? : string) : Promise<void>
+get(path : string, actor : Actor) : Promise<StoredFile>
+delete(path : string, actor : Actor) : Promise<void>
+list(prefix : string, actor : Actor) : Promise<Array<StoredFileInfo>>
+
+// types:
+StoredFile     = { path, contents : Uint8Array, contentType, size, lastModified : Date }
+StoredFileInfo = StoredFile without contents
+```
+
+```ts
+const files = FileStorageFactory.instance();
+await files.put(actor, "reports/q3.csv", bytes, "text/csv");
+const report = await files.get("reports/q3.csv", actor);
+```
+
+- Paths are relative, `/`-separated, and may not contain `..`.
+- `get` of an unknown path throws `No file found at "..."`.
+- Env var: **`ANBARIC_FILE_STORAGE_TYPE`** (`cloud` deployed; local disk otherwise, under
+  `ANBARIC_FILE_STORAGE_PATH` or the temp directory).
+
+---
+
 ## `PromptManager`
 
 Versioned prompts - instructions plus an optional output schema - owned by the

package/docs/api/typescript.md

@@ -9,7 +9,7 @@ import {
     StateMachine, State, Terminal, Action, Await, Transition,
     Job, PropertyDefinition,
     Code, Human, SystemActor, Agent, OpenAIAgent, AnthropicAgent, GeminiAgent, RemoteLLMAgenticAction,
-    JsonStoreFactory, SecretStoreFactory, SqlStoreFactory, PromptManagerFactory,
+    JsonStoreFactory, SecretStoreFactory, SqlStoreFactory, FileStorageFactory, PromptManagerFactory,
     registerEntitlement, hasEntitlement,
 } from "anbaric";
 
@@ -27,7 +27,7 @@ An Anbaric app is a standard Node.js **ESM** program in TypeScript: set
   `Actor`.
 - **[Actors and agents](actors-and-agents.md)** — `Code`, `Human`,
   `SystemActor`, `Agent`, `RemoteLLMAgenticAction`, `OpenAIAgent`, `AnthropicAgent`, `GeminiAgent`.
-- **[Stores](stores.md)** — `JsonStore`, `SecretStore`, `SqlStore`,
+- **[Stores](stores.md)** — `JsonStore`, `SecretStore`, `SqlStore`, `FileStorage`,
   `PromptManager` and their factories, plus `JsonSchema`.
 - **[Entitlements](../features/entitlements.md)** — `registerEntitlement`,
   `hasEntitlement`.
@@ -60,7 +60,7 @@ smaller surface:
 
 | Package | Contents |
 | --- | --- |
-| [`anbaric-tsapi`](https://npmjs.com/package/anbaric-tsapi) | Interfaces and value classes: `Job`, `State`, `Action`, `Await`, `Transition`, `Actor`, `JsonStore`, `SecretStore`, `SqlStore`, `Auditor`. |
+| [`anbaric-tsapi`](https://npmjs.com/package/anbaric-tsapi) | Interfaces and value classes: `Job`, `State`, `Action`, `Await`, `Transition`, `Actor`, `JsonStore`, `SecretStore`, `SqlStore`, `FileStorage`, `Auditor`. |
 | [`anbaric-state-machine`](https://npmjs.com/package/anbaric-state-machine) | `StateMachine`, actors, agents, and in-memory implementations. |
 | [`anbaric-data-store`](https://npmjs.com/package/anbaric-data-store) | The document, secret and SQL stores. |
 | [`anbaric-impl-cloud`](https://npmjs.com/package/anbaric-impl-cloud) | The clients used when an app is deployed. |

package/docs/features/documents-and-secrets.md

@@ -66,6 +66,7 @@ You don't — the factories do, from the environment:
 | --- | --- | --- | --- | --- |
 | Documents | `JsonStoreFactory.instance(collection, schema?)` | `ANBARIC_JSON_STORE_TYPE` | in-memory | platform (`cloud`) |
 | Secrets | `SecretStoreFactory.instance()` | `ANBARIC_SECRET_STORE_TYPE` | in-memory (encrypted) | platform (`cloud`) |
+| Files | `FileStorageFactory.instance()` | `ANBARIC_FILE_STORAGE_TYPE` | local disk | platform (`cloud`) |
 
 The platform sets these variables when your app is deployed. Don't set them
 yourself. See [Environment and factories](../api/environment.md).
@@ -81,4 +82,5 @@ automatically.
 ## Next
 
 - [The SQL store](sql-store.md) — a relational database for structured data
+- [File storage](file-storage.md) — bytes at a path
 - [API: Stores](../api/stores.md)

package/docs/features/file-storage.md

@@ -0,0 +1,50 @@
+# File storage
+
+Some data is a file: a generated report, an uploaded CSV, an image a job
+produced. `FileStorage` keeps bytes at a path, with a content type, and is
+obtained from a factory and used with an actor so every access is audited. Like
+the other stores it's local on your machine and platform-backed once deployed —
+no code change.
+
+## Putting and getting files
+
+```ts
+import {FileStorageFactory} from "anbaric";
+
+const files = FileStorageFactory.instance();
+
+await files.put(actor, "reports/q3.csv", new TextEncoder().encode("a,b"), "text/csv");
+
+const report = await files.get("reports/q3.csv", actor);
+report.contents;        // Uint8Array
+report.contentType;     // "text/csv"
+report.size;            // 3
+report.lastModified;    // Date
+
+const inReports = await files.list("reports/", actor);   // paths, sizes, dates — no contents
+await files.delete("reports/q3.csv", actor);
+```
+
+Paths are plain relative paths with `/` separators — `reports/q3.csv`, never
+`/reports/q3.csv` or anything containing `..`. The content type defaults to
+`application/octet-stream` when you don't give one. Getting an unknown path
+throws `No file found at "..."`.
+
+`list` takes a prefix and returns everything under it; pass `""` for every
+file. It returns metadata only, so listing a large store never loads the bytes.
+
+## Where files go
+
+**Locally** files live on disk under a temporary directory — `/tmp/anbaric/files`
+on macOS and Linux, the equivalent temp folder on Windows — so a restart keeps
+them and a reboot may not. Point `ANBARIC_FILE_STORAGE_PATH` at a directory to
+keep them somewhere permanent.
+
+**Deployed** files live in your tenant's storage, owned by your app: a path is
+private to the app that wrote it, so two apps can use the same path without
+colliding. The **Storage** page in the console lists what each app has stored.
+
+## Next
+
+- [Documents and secrets](documents-and-secrets.md) — the JSON and secret stores
+- [API: Stores](../api/stores.md)

package/docs/patterns/modelling-workflows.md

@@ -98,6 +98,20 @@ amount.required = true;
 amount.validation = (v) => typeof v === "number" && v > 0;
 ```
 
+Give every property that is not a plain string an **`example`**. The console's
+Start dialog opens on a JSON object built from the schema, and the example is
+what it shows for that property; without one it can only guess from the name,
+and for anything it cannot place it puts `null`. A job started that way then
+runs straight into your actions, so read such properties with a default:
+
+```ts
+const companies = new PropertyDefinition("companies");
+companies.example = [{ slug: "acme", companyName: "Acme Corp" }];
+
+// in an action
+const companies = job.properties.get("companies") ?? [];
+```
+
 ## See also
 
 - [State machines](../features/state-machines.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric",
-  "version": "1.54.0",
+  "version": "1.56.0",
   "description": "Everything needed to write an Anbaric app: state machines, jobs, document and secret stores, local in-memory implementations and the Anbaric Cloud clients",
   "license": "MIT",
   "type": "module",
@@ -24,9 +24,9 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "anbaric-impl-cloud": "^1.54.0",
-    "anbaric-data-store": "^1.54.0",
-    "anbaric-state-machine": "^1.54.0",
-    "anbaric-tsapi": "^1.54.0"
+    "anbaric-impl-cloud": "^1.56.0",
+    "anbaric-data-store": "^1.56.0",
+    "anbaric-state-machine": "^1.56.0",
+    "anbaric-tsapi": "^1.56.0"
   }
 }