@onyx.dev/onyx-database 0.2.0 → 0.3.0

package/README.md

@@ -122,6 +122,9 @@ Generate directly from the API (using the same credential resolver as `init()`):
 npx onyx-gen --source api --out ./src/onyx/types.ts --name OnyxSchema
 ```
 
+With `--source api`, `onyx-gen` calls the Schema API (same as `onyx-schema get`) using the
+standard config chain (env, project file, home profile).
+
 Timestamp attributes are emitted as `Date` fields by default. When saving,
 `Date` values are automatically serialized to ISO timestamp strings. Pass
 `--timestamps string` to keep timestamps as ISO strings in generated types.
@@ -132,6 +135,67 @@ Or from a local schema file you export from the console:
 npx onyx-gen --source file --schema ./onyx.schema.json --out ./src/onyx/types.ts --name OnyxSchema
 ```
 
+Run it with no flags to use the defaults: `onyx-gen` reads `./onyx.schema.json` and writes to `./onyx/types.ts`.
+
+### Manage schemas from the CLI
+
+Publish or download schema JSON directly via API using the `onyx-schema` helper:
+
+```bash
+# Publish ./onyx.schema.json with publish=true by default
+onyx-schema publish
+
+# Overwrite ./onyx.schema.json with the remote schema
+onyx-schema get
+
+# Fetch only selected tables (prints to stdout; does not overwrite files)
+onyx-schema get --tables=User,Profile
+
+# Example subset output
+onyx-schema get --tables=User,Profile
+# {
+#   "tables": [
+#     {
+#       "name": "User",
+#       "attributes": [
+#         { "name": "id", "type": "string", "required": true },
+#         { "name": "email", "type": "string", "required": true }
+#       ]
+#     },
+#     {
+#       "name": "Profile",
+#       "attributes": [
+#         { "name": "id", "type": "string", "required": true },
+#         { "name": "userId", "type": "string", "required": true }
+#       ]
+#     }
+#   ]
+# }
+
+# Validate a schema file without publishing
+onyx-schema validate ./onyx.schema.json
+```
+
+When `--tables` is provided, the subset is printed to stdout instead of writing a
+file. Otherwise, the CLI writes to `./onyx.schema.json` by default.
+
+In this repo's `examples/` workspace, the following scripts wrap the same commands:
+
+```bash
+npm run schema:get       # fetch remote schema into ./onyx.schema.json
+npm run schema:validate  # validate the local schema file
+npm run schema:publish   # validate then publish the local schema
+```
+
+The CLI reuses the same configuration resolution as `onyx.init()` (env vars,
+project config, and home profile files).
+
+You can also emit to multiple paths in one run (comma-separated or by repeating `--out`):
+
+```bash
+onyx-gen --out ./src/onyx/types.ts,./apps/admin/src/onyx/types.ts
+```
+
 Use in code:
 
 ```ts
@@ -398,7 +462,75 @@ const delCount = await db
 
 ```
 
-### 5) Documents API (binary assets)
+### 5) Schema API
+
+```ts
+import { onyx } from '@onyx.dev/onyx-database';
+const db = onyx.init();
+
+// Fetch current schema (optionally filter by tables)
+const schema = await db.getSchema({ tables: ['User', 'Profile'] });
+
+// Review history
+const history = await db.getSchemaHistory();
+
+// Validate changes without applying
+await db.validateSchema({
+  revisionDescription: 'Add profile triggers',
+  entities: [
+    {
+      name: 'Profile',
+      identifier: { name: 'id', generator: 'UUID' },
+      attributes: [
+        { name: 'id', type: 'String', isNullable: false },
+        { name: 'userId', type: 'String', isNullable: false },
+      ],
+    },
+  ],
+});
+
+// Update and optionally publish
+await db.updateSchema(
+  {
+    revisionDescription: 'Publish profile changes',
+    entities: [
+      {
+        name: 'Profile',
+        identifier: { name: 'id', generator: 'UUID' },
+        attributes: [
+          { name: 'id', type: 'String', isNullable: false },
+          { name: 'userId', type: 'String', isNullable: false },
+        ],
+      },
+    ],
+  },
+  { publish: true },
+);
+```
+
+### 6) Secrets API
+
+```ts
+import { onyx } from '@onyx.dev/onyx-database';
+const db = onyx.init();
+
+// List secret metadata
+const list = await db.listSecrets();
+
+// Read a decrypted secret value
+const secret = await db.getSecret('api-key');
+
+// Create or update a secret
+await db.putSecret('api-key', {
+  value: 'super-secret',
+  purpose: 'Access to external API',
+});
+
+// Delete a secret
+await db.deleteSecret('api-key');
+```
+
+### 7) Documents API (binary assets)
 
 ```ts
 import { onyx, type OnyxDocument } from '@onyx.dev/onyx-database';
@@ -421,7 +553,7 @@ const image = await db.getDocument('logo.png', { width: 128, height: 128 });
 await db.deleteDocument('logo.png');
 ```
 
-### 6) Streaming (live changes)
+### 8) Streaming (live changes)
 
 ```ts
 import { onyx, eq } from '@onyx.dev/onyx-database';