onlybase-sdk 0.0.1

package/PUBLISH_NPM.md

@@ -0,0 +1,120 @@
+# Publish the SDK to npm (under your account)
+
+Publish **without** the private `@onlybase` scope so the package lives under your npm user.
+
+---
+
+## 1. Choose the package name
+
+- **Unscoped** (recommended): `onlybase-sdk` — install with `npm install onlybase-sdk`. The name must be free on npm.
+- **Scoped under your user**: `@YOUR_NPM_USERNAME/onlybase-sdk` — install with `npm install @YOUR_NPM_USERNAME/onlybase-sdk`. Replace `YOUR_NPM_USERNAME` with your npm login.
+
+Edit `packages/sdk/package.json` and set `"name"` to your choice (see step 3).
+
+---
+
+## 2. Log in to npm
+
+If you don’t have an account: [sign up at npmjs.com](https://www.npmjs.com/signup).
+
+In a terminal:
+
+```bash
+npm login
+```
+
+Enter your npm **username**, **password**, and **email** when asked. You can use a profile or access token instead of password if you use 2FA.
+
+Check you’re logged in:
+
+```bash
+npm whoami
+```
+
+---
+
+## 2b. If you get "403 - Two-factor authentication required"
+
+npm requires **two-factor authentication (2FA)** to publish packages (or a token that can bypass it).
+
+**Option A — Enable 2FA (recommended):**
+
+1. Go to [npmjs.com](https://www.npmjs.com) → log in → click your avatar → **Account settings**.
+2. Under **Security**, enable **Two-Factor Authentication** (auth-only or auth-and-writes).
+3. Run `npm publish` again. npm will prompt for your one-time code (app or SMS).
+
+**Option B — Use an automation token (e.g. for CI):**
+
+1. On npm: **Account settings** → **Access Tokens** → **Generate New Token**.
+2. Choose **Granular Access Token**; set package access and enable **Bypass 2FA for publish** if you need to publish without a code.
+3. Use the token when logging in: `npm login` and use the token as the password, or set `NPM_TOKEN` in the environment.
+
+After 2FA is enabled or the token is set up, run `npm publish` again from `packages/sdk`.
+
+---
+
+## 3. Set the package name and version
+
+From the **repo root**:
+
+```bash
+cd packages/sdk
+```
+
+Edit `package.json`:
+
+- Set **name** to your chosen name, e.g.:
+  - `"name": "onlybase-sdk"` (unscoped), or
+  - `"name": "@YOUR_NPM_USERNAME/onlybase-sdk"` (scoped).
+- Bump **version** if you’ve already published before (e.g. `0.0.2`). For the first publish, `0.0.1` is fine.
+
+Optional but recommended for the npm listing:
+
+- **description**: short one-liner.
+- **keywords**: e.g. `["onlybase", "backend", "sdk", "realtime", "api"]`.
+- **repository**: your Git URL.
+- **license**: e.g. `"MIT"`.
+
+---
+
+## 4. Publish
+
+From **packages/sdk**:
+
+```bash
+npm publish
+```
+
+- **Unscoped** (`onlybase-sdk`): publishes as a public package (no extra flags).
+- **Scoped** (`@youruser/onlybase-sdk`): npm will treat it as restricted by default. To make it public:
+
+  ```bash
+  npm publish --access public
+  ```
+
+After a short delay the package will appear on [npmjs.com](https://www.npmjs.com) and users can install it with the name you chose.
+
+---
+
+## 5. Update your apps to use the published package
+
+Once the package is on npm, you can stop using the workspace alias in apps that use it:
+
+- In `apps/dashboard`, `apps/example`, etc., in `package.json` replace:
+  - `"@onlybase/sdk": "workspace:*"`  
+  with  
+  - `"onlybase-sdk": "^0.0.1"` (or `"@YOUR_NPM_USERNAME/onlybase-sdk": "^0.0.1"`).
+
+Then run `bun install` (or `npm install`) and update imports from `@onlybase/sdk` to your published package name (e.g. `onlybase-sdk`).  
+If you keep the same export names in the SDK, only the import path changes.
+
+---
+
+## Quick reference
+
+| Step | Command / action |
+|------|-------------------|
+| Login | `npm login` then `npm whoami` |
+| Name in package.json | `"onlybase-sdk"` or `"@YOUR_USER/onlybase-sdk"` |
+| Publish (unscoped) | `cd packages/sdk && npm publish` |
+| Publish (scoped, public) | `cd packages/sdk && npm publish --access public` |

package/index.ts

@@ -0,0 +1,155 @@
+const defaultBaseUrl = 'https://api.onlybase.app';
+const defaultBaseWsUrl = 'wss://api.onlybase.app/ws';
+
+type Result<T> = {
+  data: T;
+  error?: string;
+};
+
+/** Payload shape for subscription events: insert, update, delete */
+export type SubscriptionEvent = 'insert' | 'update' | 'delete';
+
+/** Message received on subscription; server sends { event, collection, payload } */
+export type SubscriptionMessage = {
+  event: string;
+  collection: string;
+  payload: unknown;
+};
+
+function getBaseUrl(baseUrl?: string): string {
+  return baseUrl ?? defaultBaseUrl;
+}
+
+function getWsUrl(baseUrl?: string): string {
+  const base = getBaseUrl(baseUrl);
+  try {
+    const u = new URL(base);
+    u.protocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
+    u.pathname = u.pathname.replace(/\/?$/, '') + '/ws';
+    return u.toString();
+  } catch {
+    return defaultBaseWsUrl;
+  }
+}
+
+function client(apiKey: string, baseUrl?: string) {
+  const base = getBaseUrl(baseUrl);
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'x-api-key': apiKey,
+  };
+
+  return {
+    collection: <T>(name: string) => ({
+      async create(data: T | T[]) {
+        const response = await fetch(
+          `${base}/v1/collections/${encodeURIComponent(name)}/rows`,
+          {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(data),
+          }
+        );
+        return response.json() as Promise<Result<T | T[]>>;
+      },
+      async list(params?: { limit?: number; offset?: number; orderBy?: string; order?: 'asc' | 'desc' }) {
+        const { limit = 100, offset = 0, orderBy, order } = params || {};
+        const url = new URL(
+          `${base}/v1/collections/${encodeURIComponent(name)}/rows`
+        );
+        url.searchParams.set('limit', String(limit));
+        url.searchParams.set('offset', String(offset));
+        if (orderBy) url.searchParams.set('order_by', orderBy);
+        if (order) url.searchParams.set('order', order);
+        const response = await fetch(url.toString(), { method: 'GET', headers });
+        return response.json() as Promise<Result<T[]>>;
+      },
+      async one(id: string): Promise<Result<T>> {
+        const response = await fetch(
+          `${base}/v1/collections/${encodeURIComponent(name)}/rows/${encodeURIComponent(id)}`,
+          { method: 'GET', headers }
+        );
+        return response.json() as Promise<Result<T>>;
+      },
+      async update(id: string, data: Partial<T>) {
+        const response = await fetch(
+          `${base}/v1/collections/${encodeURIComponent(name)}/rows/${encodeURIComponent(id)}`,
+          {
+            method: 'PATCH',
+            headers,
+            body: JSON.stringify(data),
+          }
+        );
+        return response.json() as Promise<Result<T>>;
+      },
+      async delete(id: string) {
+        const response = await fetch(
+          `${base}/v1/collections/${encodeURIComponent(name)}/rows/${encodeURIComponent(id)}`,
+          { method: 'DELETE', headers }
+        );
+        return response.json() as Promise<Result<{ success: boolean }>>;
+      },
+
+      subscribe(
+        events: SubscriptionEvent,
+        onMessage: (message: SubscriptionMessage) => void
+      ) {
+        const wsBase = getWsUrl(baseUrl);
+        const url = new URL(wsBase);
+        url.searchParams.set('api_key', apiKey);
+        url.searchParams.set('collection', name);
+        url.searchParams.set('events', events);
+
+        let ws: WebSocket;
+        let closed = false;
+        const reconnectDelayMs = 2000;
+
+        function connect() {
+          if (closed) return;
+          ws = new WebSocket(url.toString());
+
+          ws.onmessage = (e) => {
+            try {
+              const msg = JSON.parse(e.data as string) as SubscriptionMessage;
+              if (msg.event && msg.collection !== undefined) {
+                onMessage(msg);
+              }
+            } catch {
+              // ignore parse errors
+            }
+          };
+
+          ws.onclose = () => {
+            if (closed) return;
+            setTimeout(connect, reconnectDelayMs);
+          };
+
+          ws.onerror = () => {
+            // close will follow; reconnect there
+          };
+        }
+
+        connect();
+
+        return {
+          unsubscribe() {
+            closed = true;
+            if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) {
+              ws.close();
+            }
+          },
+        };
+      },
+    }),
+  };
+}
+
+// Factory for creating a configured OnlyBase client
+export const OnlyBase = client;
+
+// Convenience alias so you can do: only(apiKey, baseUrl).collection('users').list()
+export const only = client;
+
+export default OnlyBase;
+
+export type OnlyBaseClient = ReturnType<typeof client>;

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "onlybase-sdk",
+  "version": "0.0.1",
+  "description": "JavaScript SDK for OnlyBase: collections, rows, and real-time subscriptions",
+  "type": "module",
+  "main": "index.ts",
+  "types": "index.ts",
+  "keywords": ["onlybase", "backend", "sdk", "realtime", "api", "collections"],
+  "license": "MIT"
+}