@fenaura/sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agah enoch wesoamo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# @fenaura/sdk
+
+Fenaura Client SDK — direct database access, auth, and storage from the browser. Zero dependencies. Works with any Fenaura BaaS backend.
+
+## Install
+
+```bash
+npm install @fenaura/sdk
+```
+
+Requires Node >= 18 (browsers: modern evergreen with `fetch`).
+
+## Quickstart
+
+First set up the same-domain proxy once per frontend (recommended for cookie auth):
+
+```bash
+npx @fenaura/auth-init
+```
+
+Then in your app:
+
+```js
+import { createClient } from '@fenaura/sdk';
+
+const fenaura = createClient('/fenaura', '<PROJECT_ID>');
+
+await fenaura.auth.signIn({ email: 'jane@example.com', password: 'secret123' });
+const { data, error } = await fenaura.from('todos').select('*').eq('done', false).limit(20);
+```
+
+Get your `<PROJECT_ID>` (project slug) from the Fenaura dashboard.
+
+## Why the `/fenaura` proxy?
+
+Fenaura auth uses `HttpOnly SameSite=Strict` session cookies. Calling the API cross-origin would drop cookies and hit CORS issues. The proxy maps same-origin `/fenaura/*` to your API, so auth just works in dev and prod with no code changes.
+
+Direct (non-proxy) mode is for backends / Node scripts:
+
+```js
+const fenaura = createClient('https://api.yours.com', '<PROJECT_ID>');
+fenaura.setSession(token); // raw token from signIn(..., { browser: false })
+```
+
+## Database
+
+```js
+// select
+await fenaura.from('users').select('id,name').eq('role', 'admin').order('created_at').limit(10);
+// insert
+await fenaura.from('users').insert({ name: 'John' });
+// update + delete are chained then awaited (Supabase-style)
+await fenaura.from('users').update({ name: 'Jane' }).eq('id', 1).execute();
+await fenaura.from('users').delete().eq('id', 1).execute();
+// upsert takes a single object only
+await fenaura.from('users').upsert({ id: 1, name: 'Jane' });
+// single row
+const user = await fenaura.from('users').select('*').eq('id', 1).single();
+```
+
+Filters: `eq, neq, gt, gte, lt, lte, like, ilike, in, is, contains, containedBy, overlaps, textSearch, not, or`. Table/column names are validated client-side.
+
+## Auth
+
+```js
+await fenaura.auth.signUp({ email, password });
+await fenaura.auth.signIn({ email, password });
+await fenaura.auth.signOut();
+await fenaura.auth.getUser();    // current user via cookie or Bearer
+await fenaura.auth.getSession();
+
+// OAuth (12 providers: google, github, microsoft, apple, ...)
+const { data } = await fenaura.auth.signInWithOAuth('google', { redirectTo: 'https://app.yours.com/auth/callback' });
+// non-web / backend: { browser: false } returns { data: { url } }, then:
+await fenaura.auth.exchangeCodeForSession(code);
+
+// email verification / password reset / magic link
+await fenaura.auth.sendVerificationCode({ email });
+await fenaura.auth.submitVerificationCode({ email, code });
+await fenaura.auth.sendPasswordReset({ email });
+await fenaura.auth.confirmPasswordReset({ email, code, newPassword });
+await fenaura.auth.sendMagicLink({ email });
+await fenaura.auth.verifyMagicCode({ email, code });
+```
+
+Pass `{ browser: false }` to `signUp/signIn/submitVerificationCode/confirmPasswordReset/verifyMagicCode` in non-browser contexts to get the raw token in `data.token` instead of a cookie.
+
+## Storage
+
+Chunked (1 MiB), resumable per-chunk retry, with progress:
+
+```js
+const { data, error } = await fenaura.storage.from('avatars').upload('user1.jpg', file, {
+  compress: true, // on-device image resize / gzip before upload
+  onProgress: ({ sentBytes, totalBytes }) => console.log(sentBytes / totalBytes),
+});
+const dl = await fenaura.storage.from('avatars').download('user1.jpg');
+const url = fenaura.storage.from('avatars').getPublicUrl('user1.jpg'); // session-gated, needs cookie
+const signed = await fenaura.storage.from('avatars').createSignedUrl('user1.jpg', 3600); // public HMAC link
+```
+
+`compressFile(file, opts)` is also exported standalone. Images use canvas, other files use `CompressionStream`.
+
+## TypeScript
+
+Types ship built-in:
+
+```ts
+import { createClient, type FenauraClient } from '@fenaura/sdk';
+```
+
+## Bins
+
+This package also ships the proxy installer:
+
+```bash
+npx -p @fenaura/sdk fenaura-init
+```
+
+Prefer the standalone `npx @fenaura/auth-init`.
+
+## License
+
+MIT — see LICENSE.

package/bin/init.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+// npx @fenaura/auth-init — run from your frontend folder.
+// Writes the /fenaura/* proxy files your host needs. Idempotent.
+const fs = require('fs');
+const path = require('path');
+
+const argv = process.argv.slice(2);
+const apiFlag = argv.find((a) => a.startsWith('--api='));
+const API = apiFlag ? apiFlag.split('=')[1] : (process.env.FENAURA_API || 'http://localhost:8080');
+const RULE_LINE = `/fenaura/*  ${API}/:splat  200`;
+const cwd = process.cwd();
+
+// Outside an app folder? Ask the user to confirm cwd is their frontend root.
+async function confirmRoot() {
+  if (fs.existsSync(path.join(cwd, 'package.json'))) return;
+  const rl = require('readline').createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise((resolve) => rl.question(`No package.json here. Is this your frontend root? (${cwd}) [Y/n] `, resolve));
+  rl.close();
+  if (!/^(y|yes)?\s*$/i.test(answer || '')) {
+    console.error('Aborted — cd into your frontend folder first, then re-run.');
+    process.exit(1);
+  }
+}
+
+async function main() {
+  await confirmRoot();
+  const report = [];
+  const has = (f) => fs.existsSync(path.join(cwd, f));
+  const hasRule = (f) => has(f) && fs.readFileSync(path.join(cwd, f), 'utf8').includes('/fenaura');
+
+  // 1. public/_redirects (Netlify + Cloudflare Pages read this)
+  const pubDir = path.join(cwd, 'public');
+  const redirectsFile = path.join(pubDir, '_redirects');
+  if (has('public/_redirects')) {
+    const cur = fs.readFileSync(redirectsFile, 'utf8');
+    const lines = cur.split('\n');
+    const idx = lines.findIndex(l => l.includes('/fenaura'));
+    if (idx !== -1) {
+      if (lines[idx].trim() === RULE_LINE) {
+        report.push('kept  public/_redirects (rule already present)');
+      } else {
+        lines[idx] = RULE_LINE;
+        fs.writeFileSync(redirectsFile, lines.join('\n'));
+        report.push('fixed public/_redirects (corrected tampered rule)');
+      }
+    } else {
+      fs.appendFileSync(redirectsFile, (cur.length && !cur.endsWith('\n') ? '\n' : '') + RULE_LINE + '\n');
+      report.push('wrote public/_redirects');
+    }
+  } else {
+    fs.mkdirSync(pubDir, { recursive: true });
+    fs.writeFileSync(redirectsFile, RULE_LINE + '\n');
+    report.push('wrote public/_redirects');
+  }
+
+  // 2. vercel.json rewrites (Vercel only; ignored elsewhere)
+  const vercelPath = path.join(cwd, 'vercel.json');
+  const rewrite = { source: '/fenaura/:path*', destination: `${API}/:path*` };
+  let vercel = has('vercel.json') ? JSON.parse(fs.readFileSync(vercelPath, 'utf8')) : {};
+  vercel.rewrites = vercel.rewrites || [];
+  const existingIdx = vercel.rewrites.findIndex((r) => r.source && r.source.startsWith('/fenaura'));
+  if (existingIdx !== -1) {
+    const curDest = vercel.rewrites[existingIdx].destination;
+    if (curDest === rewrite.destination) {
+      report.push('kept  vercel.json (rule already present)');
+    } else {
+      vercel.rewrites[existingIdx].destination = rewrite.destination;
+      fs.writeFileSync(vercelPath, JSON.stringify(vercel, null, 2) + '\n');
+      report.push('fixed vercel.json (corrected tampered destination)');
+    }
+  } else {
+    vercel.rewrites.push(rewrite);
+    fs.writeFileSync(vercelPath, JSON.stringify(vercel, null, 2) + '\n');
+    report.push('wrote vercel.json');
+  }
+
+  // 3. Dev proxy: write it directly (Vite / Next / SvelteKit / Astro / Nuxt detected by config file)
+  const PROXY_BLOCK = `'/fenaura': { target: '${API}', changeOrigin: true, rewrite: (p) => p.replace(/^\\/fenaura/, '') }`;
+  const viteCfg = fs.readdirSync(cwd).find((f) => /^vite\.config\./.test(f));
+  const nextCfg = fs.readdirSync(cwd).find((f) => /^next\.config\./.test(f));
+  // Additional vite-based frameworks fallback: SvelteKit, Astro, Nuxt all use vite under the hood
+  const svelteCfg = !viteCfg && fs.existsSync(path.join(cwd, 'svelte.config.js')) ? 'svelte.config.js' : null;
+  const astroCfg = !viteCfg && fs.existsSync(path.join(cwd, 'astro.config.mjs')) ? 'astro.config.mjs' : null;
+  const nuxtCfg = !viteCfg && fs.existsSync(path.join(cwd, 'nuxt.config.ts')) ? 'nuxt.config.ts' : null;
+  const fallbackVite = svelteCfg || astroCfg || nuxtCfg;
+  if (viteCfg) {
+    const vp = path.join(cwd, viteCfg);
+    let src = fs.readFileSync(vp, 'utf8');
+    if (src.includes('/fenaura')) {
+      // already has proxy — correct it if API mismatched (tampered)
+      if (src.includes(API)) {
+        report.push(`kept  ${viteCfg} (proxy already present)`);
+      } else {
+        // replace target URL inside the fenaura block
+        src = src.replace(/(['"]\/fenaura['"]\s*:\s*\{\s*target:\s*['"])[^'"]+(['"])/, `$1${API}$2`);
+        // also handle json-style source destination case (next) not here
+        fs.writeFileSync(vp, src);
+        report.push(`fixed ${viteCfg} (corrected tampered API target → ${API})`);
+      }
+    } else if (/server\s*:\s*\{[^}]*proxy\s*:/.test(src)) {
+      // server.proxy exists — append our entry inside it
+      src = src.replace(/(proxy\s*:\s*\{)/, `$1\n      ${PROXY_BLOCK},`);
+      fs.writeFileSync(vp, src);
+      report.push(`wrote ${viteCfg} (appended to server.proxy)`);
+    } else if (/defineConfig\(\s*\{/.test(src)) {
+      // no server key — add one
+      src = src.replace(/(defineConfig\(\s*\{)/, `$1\n  server: {\n    proxy: {\n      ${PROXY_BLOCK},\n    },\n  },`);
+      fs.writeFileSync(vp, src);
+      report.push(`wrote ${viteCfg} (added server.proxy)`);
+    } else {
+      report.push(`${viteCfg} has no defineConfig({...) — add manually:`);
+      report.push(`  ${PROXY_BLOCK}`);
+    }
+  } else if (nextCfg) {
+    report.push('next detected — rewrites() needs an async function; add manually:');
+    report.push(`  { source: '/fenaura/:path*', destination: '${API}/:path*' }`);
+  } else if (fallbackVite) {
+    // SvelteKit / Astro / Nuxt: they all proxy via vite underneath, but config shape varies
+    // For these, ensure public/_redirects covers prod and print the vite snippet for dev
+    report.push(`${fallbackVite} detected (vite-based) — add to vite server.proxy for dev:`);
+    report.push(`  ${PROXY_BLOCK}`);
+    report.push('  (public/_redirects already covers prod)');
+  } else {
+    // No framework config (plain HTML/CSS/JS): wire VS Code Live Server proxy.
+    const vsDir = path.join(cwd, '.vscode');
+    const vsPath = path.join(vsDir, 'settings.json');
+    let settings = {};
+    if (fs.existsSync(vsPath)) {
+      try { settings = JSON.parse(fs.readFileSync(vsPath, 'utf8')); } catch { settings = {}; }
+    }
+    const proxy = (settings['liveServer.settings.proxy'] = settings['liveServer.settings.proxy'] || {});
+    const expectedUri = 'http://localhost:3000/fenaura';
+    if (proxy.baseUri === '/fenaura' && proxy.proxyUri === expectedUri) {
+      report.push('kept  .vscode/settings.json (Live Server proxy already present)');
+    } else if (proxy.baseUri === '/fenaura') {
+      proxy.enable = true;
+      proxy.baseUri = '/fenaura';
+      proxy.proxyUri = expectedUri;
+      fs.mkdirSync(vsDir, { recursive: true });
+      fs.writeFileSync(vsPath, JSON.stringify(settings, null, 2) + '\n');
+      report.push('fixed .vscode/settings.json (corrected tampered proxyUri)');
+    } else {
+      proxy.enable = true;
+      proxy.baseUri = '/fenaura';
+      // Via local nginx (:3000), which strips /fenaura — Live Server can't rewrite paths itself.
+      proxy.proxyUri = 'http://localhost:3000/fenaura';
+      fs.mkdirSync(vsDir, { recursive: true });
+      fs.writeFileSync(vsPath, JSON.stringify(settings, null, 2) + '\n');
+      report.push('wrote .vscode/settings.json (Live Server proxies /fenaura to dev API)');
+    }
+  }
+
+  const wroteAny = report.some(r => r.startsWith('wrote') || r.startsWith('fixed'));
+  console.log('\n' + (wroteAny ? '✓ Fenaura auth proxy setup — done' : '✓ Fenaura auth proxy setup — already configured') + '\n' + report.map((r) => '  ' + r).join('\n'));
+  if (wroteAny) console.log('\n  → You should see "wrote public/_redirects" and "wrote vercel.json" above (or "fixed …" if a tampered file was corrected). If you see "kept … (already present)" it was already configured — you are good to go.');
+  else console.log('\n  → Nothing to write — proxy files were already present. You are good to go.');
+  console.log('\nFrontend calls (copy-paste, project ID from dashboard):');
+  console.log("  fetch('/fenaura/auth/dp/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, credentials: 'include', body: JSON.stringify({ email, password, project_id: '<PROJECT_ID>' }) })");
+
+  // 4. Ensure JS intellisense for SDK in plain JS projects
+  const hasTsConfig = fs.existsSync(path.join(cwd, 'tsconfig.json'));
+  const hasJsConfig = fs.existsSync(path.join(cwd, 'jsconfig.json'));
+  if (!hasTsConfig && !hasJsConfig) {
+    const jsconfig = {
+      compilerOptions: {
+        target: "ES2020",
+        module: "ESNext",
+        moduleResolution: "bundler",
+        allowJs: true,
+        checkJs: false,
+        jsx: "react-jsx",
+        noImplicitAny: false
+      },
+      include: ["src"]
+    };
+    try {
+      fs.writeFileSync(path.join(cwd, 'jsconfig.json'), JSON.stringify(jsconfig, null, 2) + '\n');
+      report.push('wrote jsconfig.json (enables SDK intellisense for JS)');
+    } catch {}
+  }
+
+  // 5. Ensure SDK is installed if run via npx (one-command experience)
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    const hasSdk = deps['@fenaura/client'] || deps['@fenaura/sdk'] || deps['fenaura'];
+    if (!hasSdk) {
+      console.log('\n  → SDK not in package.json — installing @fenaura/sdk ...');
+      const { spawnSync } = require('child_process');
+      const res = spawnSync('npm', ['install', '@fenaura/sdk', '--save'], { stdio: 'inherit', cwd });
+      if (res.status !== 0) console.log('  (auto-install failed — run: npm install @fenaura/sdk)');
+      else console.log('  ✓ @fenaura/client installed');
+    }
+  } catch { /* no package.json or parse fail — skip auto-install */ }
+
+  // 6. Detect how the dev server is running + print next steps.
+  const net = require('net');
+  function portOpen(port) {
+    return new Promise((resolve) => {
+      const s = net.connect(port, '127.0.0.1');
+      s.on('connect', () => { s.end(); resolve(true); });
+      s.on('error', () => resolve(false));
+      setTimeout(() => { s.destroy(); resolve(false); }, 800);
+    });
+  }
+  (async () => {
+    const stack = viteCfg ? 'vite' : nextCfg ? 'next' : 'live-server';
+    const startCmd = stack === 'vite' || stack === 'next' ? 'npm run dev' : 'Go Live (VS Code status bar)';
+    const defaults = stack === 'vite' ? [5173] : stack === 'next' ? [3000] : [5500];
+    const open = [];
+    for (const p of [...defaults, 5173, 5174, 5199, 5500, 5501, 3000, 8080]) {
+      if (await portOpen(p)) open.push(p);
+    }
+    console.log('\nNext steps:');
+    console.log(`  1. Start dev: ${startCmd}   (detected stack: ${stack})`);
+    console.log(`  2. Open the page (local ports answering now: ${open.length ? open.join(', ') : 'none yet — start the server first'})`);
+    console.log('  3. Click login — expect session_minted + a fenaura_eusid_* cookie on YOUR domain (devtools → Application → Cookies).');
+    console.log('  4. Public URL test: forward the dev port in VS Code (Ports → Public, protocol http) and open the tunnel link.');
+    console.log('  5. Deploy: the _redirects/vercel.json files proxy /fenaura/* in prod — no code changes.\n');
+  })();
+
+}
+
+main().catch((e) => { console.error(e.message); process.exit(1); });