@nestcorehq/node 0.0.0-stage → 0.16.0

package/README.md

@@ -1,3 +1,282 @@
-# Temporary Holding Version
+# @nestcorehq/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official Node.js SDK for the NestCore platform — database, auth, edge
+functions, storage, realtime, analytics, and migrations.
+
+> Server-side SDK. The API key is a credential — keep it on the server, never
+> ship it to a browser. For client apps, use the anon key (RLS-enforced).
+
+## Install
+
+```bash
+npm install @nestcorehq/node
+```
+
+## Quick start
+
+```ts
+import { createClient } from '@nestcorehq/node';
+
+// Only the API key is required — the project slug is decoded from the key's
+// JWT, and baseUrl defaults to https://api.nestcore.io.
+const client = createClient({ apiKey: process.env.NESTCORE_API_KEY! });
+
+// Local dev / self-host:
+// createClient({ apiKey, baseUrl: 'http://localhost:3002' })
+```
+
+## Database
+
+### Fluent query builder (recommended)
+
+A Supabase-style, chainable builder. Every value is bound (`$1, $2, …`) — never
+string-interpolated — and RLS still applies.
+
+```ts
+const { data, error } = await client.db
+  .from('posts')
+  .eq('status', 'published')
+  .gt('views', 100)
+  .order('created_at', { ascending: false })
+  .limit(10)
+  .select('id, title, views');           // → { rows, total }
+
+// One row
+const { data: post } = await client.db.from('posts').eq('id', id).single();
+// First row or null (no error when empty)
+const { data: maybe } = await client.db.from('posts').eq('slug', s).maybeSingle();
+```
+
+Filter operators: `eq, neq, gt, gte, lt, lte, like, ilike, in, is`.
+Pagination: `limit(n)`, `range(from, to)` (inclusive), `page(n, size)`.
+Ordering: `order(col, { ascending })`.
+
+Writes:
+
+```ts
+await client.db.from('posts').insert({ title: 'Hello' });
+await client.db.from('posts').update(id, { title: 'Edited' });
+await client.db.from('posts').delete(id);
+```
+
+### Raw SQL (full power)
+
+```ts
+const { data } = await client.db.query(
+  'SELECT * FROM users WHERE email = $1', [email],   // always parameterize
+);
+// data: { rows, rowCount, fields }
+```
+
+## Type generation
+
+Generate TypeScript interfaces from your live schema (NestCore's
+`supabase gen types` equivalent):
+
+```ts
+import { writeFileSync } from 'fs';
+import { generateTypes } from '@nestcorehq/node';
+
+writeFileSync('nestcore.types.ts', await generateTypes(client.db));
+```
+
+```ts
+// then:
+import type { Database, Posts } from './nestcore.types';
+const { data } = await client.db.from('posts').eq('id', id).single<Posts>();
+```
+
+Excludes `auth_*` / internal tables by default; pass `{ tables }` or `{ exclude }`
+to customize.
+
+## Migrations
+
+Versioned, checksummed SQL migrations with a registry table, sequential
+execution, and rollback.
+
+```bash
+migrations/
+  001_init.sql
+  002_add_posts.sql
+```
+
+Each file may declare a rollback with a `-- migrate:down` marker:
+
+```sql
+-- 002: add posts
+CREATE TABLE posts (id uuid PRIMARY KEY DEFAULT gen_random_uuid(), title text);
+
+-- migrate:down
+DROP TABLE posts;
+```
+
+```ts
+// Migrations run DDL — use a service-role key.
+const admin = createClient({ apiKey: process.env.NESTCORE_SERVICE_KEY!, migrationsDir: 'migrations' });
+
+await admin.migrations.runAll();            // apply all pending (sequential, stop-on-failure)
+await admin.migrations.runOne('002');       // apply one
+await admin.migrations.rollback();          // roll back the most recent (runs its -- migrate:down)
+await admin.migrations.rollback('002');     // roll back a specific one
+await admin.migrations.getStatus();         // [{ migrationId, status, applied, checksumMismatch }]
+admin.migrations.createMigration('add tags'); // scaffold 003_add_tags.sql
+await admin.migrations.seed('seed.sql');    // run a (re-runnable) seed script, not recorded
+```
+
+Safety: migrations never run in parallel, completed ones are never re-run, and a
+migration whose file changed after being applied (checksum mismatch) aborts the
+run. Each file/section runs inside one transaction — keep scripts
+transaction-safe (no `CREATE INDEX CONCURRENTLY`).
+
+## Auth
+
+```ts
+await client.auth.signUp({ email, password });
+await client.auth.signIn({ email, password });
+```
+
+### Calling auth from your server
+
+Auth endpoints are throttled per client IP. When your server calls them for its users (a Next.js server action, an API route), every user would share your server's IP and its limit. Pass the user's IP with the **service-role key** and each user gets their own bucket; the same IP goes into the auth audit log:
+
+```ts
+const client = createClient({
+  apiKey: process.env.NESTCORE_SERVICE_ROLE_KEY!, // never ship this key to a browser
+  clientIp: userIp, // e.g. the first address of x-forwarded-for set by YOUR proxy
+});
+await client.auth.signIn({ email, password });
+```
+
+`clientIp` is sent as `X-NestCore-Client-IP` and must be a single IPv4 or IPv6 address. The API ignores it on requests made with the anon key or a user token, so a browser can't choose its own bucket. Create one client per request.
+
+Project auth answers `429` with a `code` when a limit from the project's auth settings is reached: `OTP_RATE_LIMITED` (too many wrong codes), `OTP_REQUEST_LIMIT` (too many codes requested for one email in an hour), `ACCOUNT_LOCKED` (too many wrong passwords).
+
+## Edge functions
+
+```ts
+await client.functions.invoke('my-function', { body: { data: 'test' } });
+```
+
+## Storage
+
+```ts
+await client.storage.from('avatars').upload(path, file);
+```
+
+## Realtime
+
+```ts
+const ch = client.channel('orders')
+  .on('postgres_changes', { event: 'INSERT', table: 'orders' }, (e) => console.log(e.new))
+  .subscribe();
+```
+
+On Node < 22 pass a WebSocket constructor: `createClient({ ..., realtimeOptions: { WebSocket } })`.
+
+## AI
+
+Chat, streaming, tool calls and embeddings through the project's own provider keys (Console → Project Settings → AI). Calls need a signed-in user or the service-role key.
+
+```ts
+const { data } = await client.ai.chat({ messages: [{ role: 'user', content: 'Summarise my last order' }] });
+
+for await (const ev of client.ai.chatStream({ messages })) {
+  if (ev.type === 'delta') process.stdout.write(ev.text);
+  if (ev.type === 'error') console.error(ev.code, ev.message);
+}
+
+const { data: vectors } = await client.ai.embed(['first', 'second']); // 768 dimensions
+```
+
+Tools: pass `tools: [{ name, description, parameters }]`; run each of `data.toolCalls`, then send the reply back as `{ role: 'assistant', content: null, toolCalls }` plus one `{ role: 'tool', toolCallId, content }` per call. See https://nestcore.io/docs/ai-gateway.
+
+### Memory, collections, threads, semantic search
+
+```ts
+// Memory: facts about the signed-in user (near-duplicates update the same memory)
+await client.memory.add('Prefers vegetarian recipes', { kind: 'preference' });
+const { data: mem } = await client.memory.search('what should I cook?'); // mem.degraded = keyword fallback
+
+// Collections: documents chunked, embedded and searched (hybrid vector + keyword)
+await admin.collections.create({ name: 'handbook' });                       // service-role key
+await admin.collections.from('handbook').ingest({ url: 'https://example.com/guide.pdf' }, { wait: true });
+const { data: hits } = await client.collections.from('handbook').search('How do refunds work?');
+
+// Threads: saved conversations; replies stream and are stored as they arrive
+const { data: thread } = await client.ai.threads.create({ title: 'Trip' });
+for await (const ev of client.ai.threads.from(thread.id).run({ input: 'Plan a weekend', memory: true, collections: ['handbook'] })) {
+  if (ev.type === 'delta') process.stdout.write(ev.text);
+  if (ev.type === 'citation') console.log(`[${ev.index}]`, ev.title);
+}
+
+// Automatic embeddings (Console → AI → Embeddings), then search a table by meaning under RLS
+const { data } = await client.db.from('articles').eq('published', true).semantic('body_embedding', 'reset my password', { k: 5 });
+```
+
+See https://nestcore.io/docs/memory-api, /docs/collections, /docs/threads and /docs/embeddings.
+
+#### Your own embeddings, trust and batches
+
+Memory and collections also take vectors from your own (e.g. local) embedding model; the server then calls no provider and charges nothing. Search compares only vectors of the same `model` and size.
+
+```ts
+const model = 'nomic-embed-text-v1.5';
+await client.memory.add('Prefers tea', { embedding: vec, model, metadata: { trust: 'user' } });
+await client.memory.search({ queryEmbedding: q, model, trust: ['user', 'tool'] }); // text query optional
+
+// Batches: up to 100 adds, 20 searches, 500 ids / 20 subjects per call
+await client.memory.addMany([{ content: 'a', embedding: va, model }, { content: 'b', embedding: vb, model }]);
+const { data: batch } = await client.memory.searchMany([{ queryEmbedding: q1, model }, { query: 'tea' }]);
+await client.memory.forgetMany({ ids: ['…'], subjects: ['owner:…'] });
+
+// A collection document from chunks you embedded (ready at once; the first chunks fix the collection's model)
+await client.collections.from('notes').addChunks([{ content: 'Refunds take 5 days', embedding: v }], { model, title: 'FAQ' });
+await client.collections.from('notes').search({ queryEmbedding: q, model, trust: 'user' });
+```
+
+### AI credits and the OpenAI-compatible API
+
+A project's own provider key always wins. Without one, the workspace's prepaid AI credit can pay (bought in Console → Settings → Billing).
+
+```ts
+const { data: credits } = await client.ai.credits();
+// { available, active, balanceUsd, monthlyCapUsd, spentThisMonthUsd, ownKeys, creditProviders }
+
+try {
+  unwrap(await client.ai.chat({ messages }));
+} catch (e) {
+  if (e instanceof NestCoreError && e.isCreditsExhausted) {
+    // e.reason: 'balance' | 'spend_cap'. Don't retry: offer e.buyUrl, or adding your own key.
+  }
+}
+
+// Any OpenAI client works against the gateway (anon key as `apikey`, the user's token as the API key)
+new OpenAI({ baseURL: client.ai.openaiBaseUrl, apiKey: accessToken, defaultHeaders: { apikey: anonKey } });
+```
+
+## Errors
+
+Every call returns `{ data, error }` (never throws) — check `error` before using
+`data`:
+
+```ts
+const { data, error } = await client.db.from('posts').select();
+if (error) { /* handle */ }
+```
+
+## Migrating from `@orbitneststudio/node`
+
+The SDK was renamed from OrbitNest to NestCore. Switch the dependency to
+`@nestcorehq/node` and update your imports; nothing else has to change at once:
+
+- The old export names still work as deprecated aliases: `OrbitNestError`
+  (same class as `NestCoreError`, so `instanceof` checks keep working),
+  `OrbitNestClient` and `OrbitNestConfig`.
+- The default `baseUrl` is now `https://api.nestcore.io`.
+- `clientIp` is now sent as `X-NestCore-Client-IP`.
+- Analytics ids stored under the old `orbitnest_*` keys are moved to the new
+  `nestcore_*` keys on first read.
+
+## License
+
+MIT