@fias/create-fias-plugin 1.0.3 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/create-fias-plugin",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "publishConfig": {
     "access": "public"
   },

package/templates/default/AGENTS.md

@@ -2,7 +2,7 @@
 
 This project is a FIAS platform plugin — a React application that runs in a sandboxed iframe within the FIAS marketplace. This file provides the context AI coding assistants need to build, test, and submit plugins effectively.
 
-For other AI tool instruction files, see `CLAUDE.md` (identical content).
+For other AI tool instruction files, see `AGENTS.md` (identical content).
 
 ## Project Structure
 
@@ -95,6 +95,73 @@ const files = await listFiles('data/'); // string[]
 await deleteFile('data/old.json');
 ```
 
+**Error handling:** Storage calls can reject on infrastructure errors. Always use `.catch()` or `try/catch` -- an unhandled rejection will crash the plugin to a white screen.
+
+### `useFiasDataStore()` — Document database
+
+**Permission:** `data:store`
+**Returns:** `FiasDataStoreApi`
+
+A document database with collections, queries, and filtering. Data persists across sessions in live mode. Each collection can be `user`-scoped (private to each user) or `shared` (visible to all users of the plugin).
+
+```tsx
+import { useFiasDataStore } from '@fias/arche-sdk';
+
+function MyComponent() {
+  const dataStore = useFiasDataStore();
+
+  // Collection management
+  await dataStore.createCollection('scores', { userScope: 'user' }); // or 'shared'
+  const collections = await dataStore.listCollections();
+  await dataStore.deleteCollection('scores');
+
+  // Document CRUD
+  await dataStore.put<MyType>('scores', 'doc-key', { score: 100, name: 'Alice' });
+  const doc = await dataStore.get<MyType>('scores', 'doc-key'); // MyType | null
+  await dataStore.delete('scores', 'doc-key');
+
+  // Query with filters, sorting, pagination
+  const results = await dataStore.query<MyType>('scores', {
+    filters: [
+      { field: 'score', op: 'gte', value: 50 },
+      { field: 'name', op: 'eq', value: 'Alice' },
+    ],
+    orderBy: { field: 'score', direction: 'desc' },
+    limit: 20,
+    cursor: nextCursor, // for pagination
+  });
+  // results = { documents: [{ key, data, updatedAt }], nextCursor: string | null }
+}
+```
+
+Also available as an imperative API outside React components:
+
+```tsx
+import { fias } from '@fias/arche-sdk';
+
+await fias.dataStore.put('scores', 'key', { score: 100 });
+const doc = await fias.dataStore.get('scores', 'key');
+```
+
+**Collection scopes:**
+
+- `user` (default): Each user sees only their own documents
+- `shared`: All users of the plugin see and share the same documents
+
+**Filter operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains` (JSONB containment), `exists`
+
+**Limits:**
+
+- 50 collections per plugin
+- 10,000 documents per collection
+- 100 KB per document
+- 100 MB total storage per plugin
+- Max 100 results per query, max 10 filters, max field path depth 5
+
+**Rate limits (per minute):** `put` 120, `get` 300, `query` 60, `delete` 60, `createCollection` 10
+
+**Error handling:** Data store calls can reject on infrastructure errors or limit violations. Always use `try/catch`. Common error codes: `COLLECTION_NOT_FOUND`, `DOCUMENT_TOO_LARGE`, `STORAGE_LIMIT_REACHED`, `RATE_LIMIT`.
+
 ### `useEntityInvocation()` — Invoke AI models
 
 **Permission:** `entities:invoke`
@@ -242,7 +309,7 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
 | `sdk`          | Yes      | SDK version range                                         |
 | `dependencies` | No       | npm packages with **exact** versions (max 20)             |
 
-**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `entities:invoke`, `entities:image_generate`
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `entities:invoke`, `entities:image_generate`
 
 **Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.
 
@@ -288,6 +355,19 @@ These are hard limits enforced by the platform. Code that violates these will fa
 
 ## Development Workflow
 
+### Check for Updates (DO THIS FIRST)
+
+**At the start of every new session**, check if the FIAS packages and tooling are up to date:
+
+```bash
+npm outdated @fias/arche-sdk @fias/plugin-dev-harness
+npx fias-dev sync --dry-run
+```
+
+If newer package versions are available, tell the user and ask if they want to update before proceeding. Stale packages can cause subtle bugs (e.g., mismatched API return types) that are hard to diagnose.
+
+If `sync --dry-run` shows pending changes, tell the user and offer to run `npx fias-dev sync` to update AI instruction files and config from the latest SDK templates. This never touches source code or project-specific files (`package.json`, `fias-plugin.json`, `src/`).
+
 ### Starting Development
 
 ```bash

package/templates/default/CLAUDE.md

@@ -95,6 +95,73 @@ const files = await listFiles('data/'); // string[]
 await deleteFile('data/old.json');
 ```
 
+**Error handling:** Storage calls can reject on infrastructure errors. Always use `.catch()` or `try/catch` -- an unhandled rejection will crash the plugin to a white screen.
+
+### `useFiasDataStore()` — Document database
+
+**Permission:** `data:store`
+**Returns:** `FiasDataStoreApi`
+
+A document database with collections, queries, and filtering. Data persists across sessions in live mode. Each collection can be `user`-scoped (private to each user) or `shared` (visible to all users of the plugin).
+
+```tsx
+import { useFiasDataStore } from '@fias/arche-sdk';
+
+function MyComponent() {
+  const dataStore = useFiasDataStore();
+
+  // Collection management
+  await dataStore.createCollection('scores', { userScope: 'user' }); // or 'shared'
+  const collections = await dataStore.listCollections();
+  await dataStore.deleteCollection('scores');
+
+  // Document CRUD
+  await dataStore.put<MyType>('scores', 'doc-key', { score: 100, name: 'Alice' });
+  const doc = await dataStore.get<MyType>('scores', 'doc-key'); // MyType | null
+  await dataStore.delete('scores', 'doc-key');
+
+  // Query with filters, sorting, pagination
+  const results = await dataStore.query<MyType>('scores', {
+    filters: [
+      { field: 'score', op: 'gte', value: 50 },
+      { field: 'name', op: 'eq', value: 'Alice' },
+    ],
+    orderBy: { field: 'score', direction: 'desc' },
+    limit: 20,
+    cursor: nextCursor, // for pagination
+  });
+  // results = { documents: [{ key, data, updatedAt }], nextCursor: string | null }
+}
+```
+
+Also available as an imperative API outside React components:
+
+```tsx
+import { fias } from '@fias/arche-sdk';
+
+await fias.dataStore.put('scores', 'key', { score: 100 });
+const doc = await fias.dataStore.get('scores', 'key');
+```
+
+**Collection scopes:**
+
+- `user` (default): Each user sees only their own documents
+- `shared`: All users of the plugin see and share the same documents
+
+**Filter operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains` (JSONB containment), `exists`
+
+**Limits:**
+
+- 50 collections per plugin
+- 10,000 documents per collection
+- 100 KB per document
+- 100 MB total storage per plugin
+- Max 100 results per query, max 10 filters, max field path depth 5
+
+**Rate limits (per minute):** `put` 120, `get` 300, `query` 60, `delete` 60, `createCollection` 10
+
+**Error handling:** Data store calls can reject on infrastructure errors or limit violations. Always use `try/catch`. Common error codes: `COLLECTION_NOT_FOUND`, `DOCUMENT_TOO_LARGE`, `STORAGE_LIMIT_REACHED`, `RATE_LIMIT`.
+
 ### `useEntityInvocation()` — Invoke AI models
 
 **Permission:** `entities:invoke`
@@ -242,7 +309,7 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
 | `sdk`          | Yes      | SDK version range                                         |
 | `dependencies` | No       | npm packages with **exact** versions (max 20)             |
 
-**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `entities:invoke`, `entities:image_generate`
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `entities:invoke`, `entities:image_generate`
 
 **Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.
 
@@ -288,6 +355,19 @@ These are hard limits enforced by the platform. Code that violates these will fa
 
 ## Development Workflow
 
+### Check for Updates (DO THIS FIRST)
+
+**At the start of every new session**, check if the FIAS packages and tooling are up to date:
+
+```bash
+npm outdated @fias/arche-sdk @fias/plugin-dev-harness
+npx fias-dev sync --dry-run
+```
+
+If newer package versions are available, tell the user and ask if they want to update before proceeding. Stale packages can cause subtle bugs (e.g., mismatched API return types) that are hard to diagnose.
+
+If `sync --dry-run` shows pending changes, tell the user and offer to run `npx fias-dev sync` to update AI instruction files and config from the latest SDK templates. This never touches source code or project-specific files (`package.json`, `fias-plugin.json`, `src/`).
+
 ### Starting Development
 
 ```bash