@deployowl/nosql 2.2.5

package/README.md

@@ -0,0 +1,107 @@
+# @deployowl/nosql
+
+Zero-config Edge NoSQL SDK for DeployOwl.
+
+Use this SDK to store, query, and manage JSON document collections on DeployOwl's global edge infrastructure from Vercel, Render, Cloud Run, Supabase, Railway, Fly.io, or any server environment.
+
+---
+
+## Installation
+
+```bash
+npm install @deployowl/nosql
+# or
+pnpm add @deployowl/nosql
+# or
+yarn add @deployowl/nosql
+```
+
+---
+
+## Quick Start
+
+### 1. Initialize the client
+
+Construct the client once at module load:
+
+```typescript
+import { createClient } from '@deployowl/nosql';
+
+const db = createClient({
+  apiKey: process.env.OWL_NOSQL_KEY!, // Your owl_ API key (min 32 chars)
+  // gatewayUrl: 'https://owlnosql.deployowl.com', // Optional default
+  // autoHashIds: true, // Auto-hash non-alphanumeric IDs to SHA-256
+});
+
+const users = db.collection('users');
+```
+
+> **Security Note:** `createClient()` must only be run in server environments. Calling it in a browser context will throw an error to prevent API key exposure.
+
+### 2. Write a document
+
+```typescript
+await users.insert('user_9482', {
+  email: 'ada@example.com',
+  plan: 'pro',
+  signupAt: Date.now(),
+  tags: ['early', 'beta']
+});
+// → { id: 'user_9482', written: true, bytes: 87 }
+```
+
+### 3. Read a document
+
+```typescript
+const ada = await users.find('user_9482');
+// → { email: 'ada@example.com', plan: 'pro', ... }
+
+// Bypass edge cache for fresh read:
+const fresh = await users.find('user_9482', { bypassCache: true });
+```
+
+### 4. Index and Query
+
+```typescript
+// Define indexed fields (once per collection):
+await users.index(['email', 'plan']);
+
+// Query documents:
+const pros = await users.query({ plan: 'pro' });
+```
+
+### 5. Delete
+
+```typescript
+await users.delete('user_9482');
+// → { deleted: true }
+```
+
+---
+
+## API Reference
+
+| Method | Signature | Description |
+|---|---|---|
+| `collection(name)` | `name: string` | Get collection handle (alphanumeric, `_`, `-`, max 64 chars). |
+| `find(id, opts?)` | `id: string`, `opts.bypassCache?: boolean` | Fetch document. Returns `T \| null`. |
+| `insert(id, payload, opts?)` | `id: string`, `payload: object`, `opts.ifMatch?: string` | Insert document. |
+| `delete(id)` | `id: string` | Delete document. |
+| `query(filter)` | `filter: object` | Query documents by indexed fields. Returns `T[]`. |
+| `list()` | — | List all document IDs in the collection. |
+| `index(fields)` | `fields: string[]` | Create indexes on collection fields. |
+| `reindex()` | — | Rebuild collection shard indexes. |
+
+---
+
+## Document & ID Rules
+
+- **ID Rules:** Alphanumeric, `_`, `-`, max 128 chars. IDs starting with `_` are reserved.
+- **Auto-Hashing:** With `autoHashIds: true`, non-conforming IDs are automatically SHA-256 hashed to `hash_<base64url>`.
+- **Errors:** Throws `OwlError` with `.code`, `.message`, `.statusCode`. `find()` swallows 404 and returns `null`.
+
+---
+
+## License
+
+Proprietary © DeployOwl. All rights reserved.

package/dist/index.d.mts

@@ -0,0 +1,49 @@
+declare function encryptRoute(path: string, apiKey: string): Promise<string>;
+declare function decryptRoute(token: string, apiKey: string): Promise<string>;
+declare class MessagePack {
+    static serialize(value: any): Uint8Array;
+    static deserialize(buffer: ArrayBuffer | Uint8Array): any;
+}
+declare class OwlError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    constructor(code: string, message: string, statusCode: number);
+}
+interface ClientOptions {
+    apiKey: string;
+    gatewayUrl?: string;
+    retry?: {
+        maxAttempts?: number;
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+        jitterMs?: number;
+    };
+    autoHashIds?: boolean;
+}
+declare function createClient(options: ClientOptions): {
+    collection: (collectionName: string) => {
+        find: <T = Record<string, any>>(id: string, findOpt?: {
+            bypassCache?: boolean;
+        }) => Promise<T | null>;
+        insert: (id: string, payload: Record<string, any>, opt?: {
+            ifMatch?: string;
+        }) => Promise<{
+            id: string;
+            written: boolean;
+            bytes: number;
+        }>;
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+        query: <T = Record<string, any>>(filter: Record<string, any>) => Promise<T[]>;
+        list: () => Promise<string[]>;
+        reindex: () => Promise<{
+            success: boolean;
+        }>;
+        index: (fields: string[]) => Promise<{
+            success: boolean;
+        }>;
+    };
+};
+
+export { type ClientOptions, MessagePack, OwlError, createClient, decryptRoute, encryptRoute };

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+declare function encryptRoute(path: string, apiKey: string): Promise<string>;
+declare function decryptRoute(token: string, apiKey: string): Promise<string>;
+declare class MessagePack {
+    static serialize(value: any): Uint8Array;
+    static deserialize(buffer: ArrayBuffer | Uint8Array): any;
+}
+declare class OwlError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    constructor(code: string, message: string, statusCode: number);
+}
+interface ClientOptions {
+    apiKey: string;
+    gatewayUrl?: string;
+    retry?: {
+        maxAttempts?: number;
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+        jitterMs?: number;
+    };
+    autoHashIds?: boolean;
+}
+declare function createClient(options: ClientOptions): {
+    collection: (collectionName: string) => {
+        find: <T = Record<string, any>>(id: string, findOpt?: {
+            bypassCache?: boolean;
+        }) => Promise<T | null>;
+        insert: (id: string, payload: Record<string, any>, opt?: {
+            ifMatch?: string;
+        }) => Promise<{
+            id: string;
+            written: boolean;
+            bytes: number;
+        }>;
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+        query: <T = Record<string, any>>(filter: Record<string, any>) => Promise<T[]>;
+        list: () => Promise<string[]>;
+        reindex: () => Promise<{
+            success: boolean;
+        }>;
+        index: (fields: string[]) => Promise<{
+            success: boolean;
+        }>;
+    };
+};
+
+export { type ClientOptions, MessagePack, OwlError, createClient, decryptRoute, encryptRoute };