@fias/create-fias-plugin 1.0.3 → 1.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,10 +1,15 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fias/create-fias-plugin",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.5",
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
7
7
|
"description": "Scaffold a new FIAS plugin arche project",
|
|
8
|
+
"scripts": {
|
|
9
|
+
"build": "pnpm build:ai-docs",
|
|
10
|
+
"build:ai-docs": "node scripts/build-ai-docs.mjs",
|
|
11
|
+
"check:ai-docs": "node scripts/build-ai-docs.mjs --check"
|
|
12
|
+
},
|
|
8
13
|
"bin": {
|
|
9
14
|
"create-fias-plugin": "index.js"
|
|
10
15
|
},
|
|
@@ -2,8 +2,6 @@
|
|
|
2
2
|
|
|
3
3
|
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.
|
|
4
4
|
|
|
5
|
-
For other AI tool instruction files, see `CLAUDE.md` (identical content).
|
|
6
|
-
|
|
7
5
|
## Project Structure
|
|
8
6
|
|
|
9
7
|
```
|
|
@@ -95,6 +93,73 @@ const files = await listFiles('data/'); // string[]
|
|
|
95
93
|
await deleteFile('data/old.json');
|
|
96
94
|
```
|
|
97
95
|
|
|
96
|
+
**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.
|
|
97
|
+
|
|
98
|
+
### `useFiasDataStore()` — Document database
|
|
99
|
+
|
|
100
|
+
**Permission:** `data:store`
|
|
101
|
+
**Returns:** `FiasDataStoreApi`
|
|
102
|
+
|
|
103
|
+
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).
|
|
104
|
+
|
|
105
|
+
```tsx
|
|
106
|
+
import { useFiasDataStore } from '@fias/arche-sdk';
|
|
107
|
+
|
|
108
|
+
function MyComponent() {
|
|
109
|
+
const dataStore = useFiasDataStore();
|
|
110
|
+
|
|
111
|
+
// Collection management
|
|
112
|
+
await dataStore.createCollection('scores', { userScope: 'user' }); // or 'shared'
|
|
113
|
+
const collections = await dataStore.listCollections();
|
|
114
|
+
await dataStore.deleteCollection('scores');
|
|
115
|
+
|
|
116
|
+
// Document CRUD
|
|
117
|
+
await dataStore.put<MyType>('scores', 'doc-key', { score: 100, name: 'Alice' });
|
|
118
|
+
const doc = await dataStore.get<MyType>('scores', 'doc-key'); // MyType | null
|
|
119
|
+
await dataStore.delete('scores', 'doc-key');
|
|
120
|
+
|
|
121
|
+
// Query with filters, sorting, pagination
|
|
122
|
+
const results = await dataStore.query<MyType>('scores', {
|
|
123
|
+
filters: [
|
|
124
|
+
{ field: 'score', op: 'gte', value: 50 },
|
|
125
|
+
{ field: 'name', op: 'eq', value: 'Alice' },
|
|
126
|
+
],
|
|
127
|
+
orderBy: { field: 'score', direction: 'desc' },
|
|
128
|
+
limit: 20,
|
|
129
|
+
cursor: nextCursor, // for pagination
|
|
130
|
+
});
|
|
131
|
+
// results = { documents: [{ key, data, updatedAt }], nextCursor: string | null }
|
|
132
|
+
}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Also available as an imperative API outside React components:
|
|
136
|
+
|
|
137
|
+
```tsx
|
|
138
|
+
import { fias } from '@fias/arche-sdk';
|
|
139
|
+
|
|
140
|
+
await fias.dataStore.put('scores', 'key', { score: 100 });
|
|
141
|
+
const doc = await fias.dataStore.get('scores', 'key');
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
**Collection scopes:**
|
|
145
|
+
|
|
146
|
+
- `user` (default): Each user sees only their own documents
|
|
147
|
+
- `shared`: All users of the plugin see and share the same documents
|
|
148
|
+
|
|
149
|
+
**Filter operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains` (JSONB containment), `exists`
|
|
150
|
+
|
|
151
|
+
**Limits:**
|
|
152
|
+
|
|
153
|
+
- 50 collections per plugin
|
|
154
|
+
- 10,000 documents per collection
|
|
155
|
+
- 100 KB per document
|
|
156
|
+
- 100 MB total storage per plugin
|
|
157
|
+
- Max 100 results per query, max 10 filters, max field path depth 5
|
|
158
|
+
|
|
159
|
+
**Rate limits (per minute):** `put` 120, `get` 300, `query` 60, `delete` 60, `createCollection` 10
|
|
160
|
+
|
|
161
|
+
**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`.
|
|
162
|
+
|
|
98
163
|
### `useEntityInvocation()` — Invoke AI models
|
|
99
164
|
|
|
100
165
|
**Permission:** `entities:invoke`
|
|
@@ -242,7 +307,7 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
|
|
|
242
307
|
| `sdk` | Yes | SDK version range |
|
|
243
308
|
| `dependencies` | No | npm packages with **exact** versions (max 20) |
|
|
244
309
|
|
|
245
|
-
**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `entities:invoke`, `entities:image_generate`
|
|
310
|
+
**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `entities:invoke`, `entities:image_generate`
|
|
246
311
|
|
|
247
312
|
**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`.
|
|
248
313
|
|
|
@@ -288,6 +353,19 @@ These are hard limits enforced by the platform. Code that violates these will fa
|
|
|
288
353
|
|
|
289
354
|
## Development Workflow
|
|
290
355
|
|
|
356
|
+
### Check for Updates (DO THIS FIRST)
|
|
357
|
+
|
|
358
|
+
**At the start of every new session**, check if the FIAS packages and tooling are up to date:
|
|
359
|
+
|
|
360
|
+
```bash
|
|
361
|
+
npm outdated @fias/arche-sdk @fias/plugin-dev-harness
|
|
362
|
+
npx fias-dev sync --dry-run
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
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.
|
|
366
|
+
|
|
367
|
+
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/`).
|
|
368
|
+
|
|
291
369
|
### Starting Development
|
|
292
370
|
|
|
293
371
|
```bash
|
|
@@ -413,3 +491,7 @@ function Settings() {
|
|
|
413
491
|
);
|
|
414
492
|
}
|
|
415
493
|
```
|
|
494
|
+
|
|
495
|
+
## See also
|
|
496
|
+
|
|
497
|
+
`CLAUDE.md` — equivalent guide with Claude-specific additions.
|
|
@@ -2,8 +2,6 @@
|
|
|
2
2
|
|
|
3
3
|
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.
|
|
4
4
|
|
|
5
|
-
For other AI tool instruction files, see `AGENTS.md` (identical content).
|
|
6
|
-
|
|
7
5
|
## Project Structure
|
|
8
6
|
|
|
9
7
|
```
|
|
@@ -95,6 +93,73 @@ const files = await listFiles('data/'); // string[]
|
|
|
95
93
|
await deleteFile('data/old.json');
|
|
96
94
|
```
|
|
97
95
|
|
|
96
|
+
**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.
|
|
97
|
+
|
|
98
|
+
### `useFiasDataStore()` — Document database
|
|
99
|
+
|
|
100
|
+
**Permission:** `data:store`
|
|
101
|
+
**Returns:** `FiasDataStoreApi`
|
|
102
|
+
|
|
103
|
+
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).
|
|
104
|
+
|
|
105
|
+
```tsx
|
|
106
|
+
import { useFiasDataStore } from '@fias/arche-sdk';
|
|
107
|
+
|
|
108
|
+
function MyComponent() {
|
|
109
|
+
const dataStore = useFiasDataStore();
|
|
110
|
+
|
|
111
|
+
// Collection management
|
|
112
|
+
await dataStore.createCollection('scores', { userScope: 'user' }); // or 'shared'
|
|
113
|
+
const collections = await dataStore.listCollections();
|
|
114
|
+
await dataStore.deleteCollection('scores');
|
|
115
|
+
|
|
116
|
+
// Document CRUD
|
|
117
|
+
await dataStore.put<MyType>('scores', 'doc-key', { score: 100, name: 'Alice' });
|
|
118
|
+
const doc = await dataStore.get<MyType>('scores', 'doc-key'); // MyType | null
|
|
119
|
+
await dataStore.delete('scores', 'doc-key');
|
|
120
|
+
|
|
121
|
+
// Query with filters, sorting, pagination
|
|
122
|
+
const results = await dataStore.query<MyType>('scores', {
|
|
123
|
+
filters: [
|
|
124
|
+
{ field: 'score', op: 'gte', value: 50 },
|
|
125
|
+
{ field: 'name', op: 'eq', value: 'Alice' },
|
|
126
|
+
],
|
|
127
|
+
orderBy: { field: 'score', direction: 'desc' },
|
|
128
|
+
limit: 20,
|
|
129
|
+
cursor: nextCursor, // for pagination
|
|
130
|
+
});
|
|
131
|
+
// results = { documents: [{ key, data, updatedAt }], nextCursor: string | null }
|
|
132
|
+
}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Also available as an imperative API outside React components:
|
|
136
|
+
|
|
137
|
+
```tsx
|
|
138
|
+
import { fias } from '@fias/arche-sdk';
|
|
139
|
+
|
|
140
|
+
await fias.dataStore.put('scores', 'key', { score: 100 });
|
|
141
|
+
const doc = await fias.dataStore.get('scores', 'key');
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
**Collection scopes:**
|
|
145
|
+
|
|
146
|
+
- `user` (default): Each user sees only their own documents
|
|
147
|
+
- `shared`: All users of the plugin see and share the same documents
|
|
148
|
+
|
|
149
|
+
**Filter operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains` (JSONB containment), `exists`
|
|
150
|
+
|
|
151
|
+
**Limits:**
|
|
152
|
+
|
|
153
|
+
- 50 collections per plugin
|
|
154
|
+
- 10,000 documents per collection
|
|
155
|
+
- 100 KB per document
|
|
156
|
+
- 100 MB total storage per plugin
|
|
157
|
+
- Max 100 results per query, max 10 filters, max field path depth 5
|
|
158
|
+
|
|
159
|
+
**Rate limits (per minute):** `put` 120, `get` 300, `query` 60, `delete` 60, `createCollection` 10
|
|
160
|
+
|
|
161
|
+
**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`.
|
|
162
|
+
|
|
98
163
|
### `useEntityInvocation()` — Invoke AI models
|
|
99
164
|
|
|
100
165
|
**Permission:** `entities:invoke`
|
|
@@ -242,7 +307,7 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
|
|
|
242
307
|
| `sdk` | Yes | SDK version range |
|
|
243
308
|
| `dependencies` | No | npm packages with **exact** versions (max 20) |
|
|
244
309
|
|
|
245
|
-
**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `entities:invoke`, `entities:image_generate`
|
|
310
|
+
**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `entities:invoke`, `entities:image_generate`
|
|
246
311
|
|
|
247
312
|
**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`.
|
|
248
313
|
|
|
@@ -288,6 +353,19 @@ These are hard limits enforced by the platform. Code that violates these will fa
|
|
|
288
353
|
|
|
289
354
|
## Development Workflow
|
|
290
355
|
|
|
356
|
+
### Check for Updates (DO THIS FIRST)
|
|
357
|
+
|
|
358
|
+
**At the start of every new session**, check if the FIAS packages and tooling are up to date:
|
|
359
|
+
|
|
360
|
+
```bash
|
|
361
|
+
npm outdated @fias/arche-sdk @fias/plugin-dev-harness
|
|
362
|
+
npx fias-dev sync --dry-run
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
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.
|
|
366
|
+
|
|
367
|
+
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/`).
|
|
368
|
+
|
|
291
369
|
### Starting Development
|
|
292
370
|
|
|
293
371
|
```bash
|
|
@@ -413,3 +491,7 @@ function Settings() {
|
|
|
413
491
|
);
|
|
414
492
|
}
|
|
415
493
|
```
|
|
494
|
+
|
|
495
|
+
## See also
|
|
496
|
+
|
|
497
|
+
`AGENTS.md` — equivalent guide for non-Claude AI tools in this project.
|