@hanzo/base 0.2.0 → 0.2.1

package/src/compat/index.ts

@@ -1,24 +1,47 @@
 /**
- * @hanzoai/base/compat -- PocketBase-compatible client re-exports.
+ * @hanzo/base/compat -- drop-in for legacy client imports.
  *
- * Provides a drop-in replacement for the `pocketbase` npm package
- * so that existing code can migrate to `@hanzoai/base` without changes.
+ * Re-exports every symbol consumers used to import from the legacy
+ * client. Switching the specifier (and only the specifier) carries
+ * existing code over with no further changes:
  *
- * Usage:
- *   import Base, { LocalAuthStore, isTokenExpired } from '@hanzoai/base/compat'
+ *   - import Base, { LocalAuthStore } from '@hanzo/base/compat'
+ *
+ * Everything here is implemented natively in @hanzo/base — no
+ * upstream package dependency.
  */
 
 export {
   default,
-  default as PocketBase,
   default as Base,
+  BaseClient,
+  MemoryAuthStore,
   LocalAuthStore,
   AsyncAuthStore,
-  BaseAuthStore,
-  isTokenExpired,
   ClientResponseError,
+  isTokenExpired,
+  getTokenPayload,
   cookieParse,
   cookieSerialize,
-  getTokenPayload,
   normalizeUnknownQueryParams,
-} from 'pocketbase'
+} from '../core/index.js'
+
+export type {
+  AuthStore,
+  AuthChangeCallback,
+  ClientConfig,
+  ListOptions,
+  ListResult,
+  BaseAuthStore,
+  BaseRecord,
+  RecordModel,
+  CollectionField,
+  CollectionModel,
+  RecordQueryOptions,
+  RecordFullListOptions,
+  FileOptions,
+  AuthResponse,
+  OAuth2Options,
+  ClientResponseErrorData,
+  CookieSerializeOptions,
+} from '../core/index.js'

package/src/core/auth-stores.ts

@@ -0,0 +1,222 @@
+/**
+ * Auth-store implementations beyond the in-memory default.
+ *
+ * Native `LocalAuthStore` / `AsyncAuthStore` implementations so the
+ * SDK has zero upstream client dependency. The shape matches the
+ * legacy client's auth stores so existing apps migrating to
+ * `@hanzo/base` keep working.
+ */
+
+import type { AuthStore, AuthChangeCallback } from './client.js'
+import type { BaseRecord } from './state.js'
+
+interface PersistedAuth {
+  token: string
+  record: BaseRecord | null
+}
+
+/**
+ * Type alias matching the upstream interface name. New code should use
+ * `AuthStore`.
+ */
+export type BaseAuthStore = AuthStore
+
+/**
+ * Synchronous localStorage-backed auth store. Suitable for browser SPAs.
+ * Falls back to in-memory storage when `window.localStorage` is absent
+ * (SSR, sandboxed iframes, etc.).
+ */
+export class LocalAuthStore implements AuthStore {
+  private _storageKey: string
+  private _listeners = new Set<AuthChangeCallback>()
+  private _memToken = ''
+  private _memRecord: BaseRecord | null = null
+
+  constructor(storageKey: string = 'base_auth') {
+    this._storageKey = storageKey
+  }
+
+  private get _storage(): Storage | null {
+    try {
+      if (typeof globalThis !== 'undefined' && 'localStorage' in globalThis) {
+        return (globalThis as { localStorage?: Storage }).localStorage ?? null
+      }
+    } catch {
+      // Access can throw in some sandboxed contexts; fall through.
+    }
+    return null
+  }
+
+  private _read(): PersistedAuth {
+    const storage = this._storage
+    if (!storage) return { token: this._memToken, record: this._memRecord }
+    try {
+      const raw = storage.getItem(this._storageKey)
+      if (!raw) return { token: '', record: null }
+      const parsed = JSON.parse(raw) as Partial<PersistedAuth>
+      return { token: parsed.token ?? '', record: parsed.record ?? null }
+    } catch {
+      return { token: '', record: null }
+    }
+  }
+
+  private _write(value: PersistedAuth): void {
+    const storage = this._storage
+    if (!storage) {
+      this._memToken = value.token
+      this._memRecord = value.record
+      return
+    }
+    try {
+      if (!value.token) {
+        storage.removeItem(this._storageKey)
+      } else {
+        storage.setItem(this._storageKey, JSON.stringify(value))
+      }
+    } catch {
+      // Quota / serialization errors fall back to memory.
+      this._memToken = value.token
+      this._memRecord = value.record
+    }
+  }
+
+  get token(): string {
+    return this._read().token
+  }
+
+  get record(): BaseRecord | null {
+    return this._read().record
+  }
+
+  get isValid(): boolean {
+    const token = this.token
+    if (!token) return false
+    try {
+      const parts = token.split('.')
+      if (parts.length !== 3) return false
+      const payload = JSON.parse(atob(parts[1].replace(/-/g, '+').replace(/_/g, '/')))
+      if (typeof payload.exp === 'number') return payload.exp > Date.now() / 1000
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  save(token: string, record: BaseRecord | null): void {
+    this._write({ token, record })
+    this._notify(token, record)
+  }
+
+  clear(): void {
+    this._write({ token: '', record: null })
+    this._notify('', null)
+  }
+
+  onChange(callback: AuthChangeCallback): () => void {
+    this._listeners.add(callback)
+    return () => {
+      this._listeners.delete(callback)
+    }
+  }
+
+  private _notify(token: string, record: BaseRecord | null): void {
+    for (const cb of this._listeners) {
+      try {
+        cb(token, record)
+      } catch {
+        // listener errors must not break notification
+      }
+    }
+  }
+}
+
+/**
+ * Async auth store — wraps any async storage backend (cookies via
+ * fetch, encrypted SecureStore on mobile, KV namespace on the edge,
+ * etc.). Reads and writes are buffered through an in-memory cache so
+ * the `token`/`record` accessors stay synchronous (matching upstream).
+ *
+ * Pass a `save` function that persists the serialized payload to your
+ * backend, and an `initial` value loaded synchronously at app boot.
+ */
+export class AsyncAuthStore implements AuthStore {
+  private _token = ''
+  private _record: BaseRecord | null = null
+  private _listeners = new Set<AuthChangeCallback>()
+  private readonly _save: (serialized: string) => Promise<void> | void
+  private readonly _clear?: () => Promise<void> | void
+
+  constructor(config: {
+    save: (serialized: string) => Promise<void> | void
+    initial?: string | null
+    clear?: () => Promise<void> | void
+  }) {
+    this._save = config.save
+    this._clear = config.clear
+    if (config.initial) {
+      try {
+        const parsed = JSON.parse(config.initial) as Partial<PersistedAuth>
+        this._token = parsed.token ?? ''
+        this._record = parsed.record ?? null
+      } catch {
+        // ignore malformed initial value
+      }
+    }
+  }
+
+  get token(): string {
+    return this._token
+  }
+
+  get record(): BaseRecord | null {
+    return this._record
+  }
+
+  get isValid(): boolean {
+    if (!this._token) return false
+    try {
+      const parts = this._token.split('.')
+      if (parts.length !== 3) return false
+      const payload = JSON.parse(atob(parts[1].replace(/-/g, '+').replace(/_/g, '/')))
+      if (typeof payload.exp === 'number') return payload.exp > Date.now() / 1000
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  save(token: string, record: BaseRecord | null): void {
+    this._token = token
+    this._record = record
+    void this._save(JSON.stringify({ token, record }))
+    this._notify()
+  }
+
+  clear(): void {
+    this._token = ''
+    this._record = null
+    if (this._clear) {
+      void this._clear()
+    } else {
+      void this._save('')
+    }
+    this._notify()
+  }
+
+  onChange(callback: AuthChangeCallback): () => void {
+    this._listeners.add(callback)
+    return () => {
+      this._listeners.delete(callback)
+    }
+  }
+
+  private _notify(): void {
+    for (const cb of this._listeners) {
+      try {
+        cb(this._token, this._record)
+      } catch {
+        // listener errors must not break notification
+      }
+    }
+  }
+}

package/src/core/client.ts

@@ -3,7 +3,7 @@
  *
  * Two API surfaces:
  *
- * 1. PocketBase-compatible: client.collection('posts').getList(...)
+ * 1. Base-compatible: client.collection('posts').getList(...)
  * 2. Direct (convenience):  client.list('posts', { filter: '...' })
  *
  * Both share the same QueryStore, RealtimeService, and AuthStore.
@@ -105,7 +105,7 @@ export class FileService {
 
   /**
    * Build a full URL to a record file.
-   * Compatible with PocketBase's pb.files.getURL().
+   * Compatible with Base's files.getURL().
    */
   getURL(record: BaseRecord, filename: string, options?: FileOptions): string {
     if (!filename || !record.id) return ''
@@ -113,7 +113,7 @@ export class FileService {
     const collectionId = (record.collectionId ?? record.collectionName ?? '') as string
     const parts = [
       this._baseUrl,
-      'api',
+      'v1',
       'files',
       encodeURIComponent(collectionId),
       encodeURIComponent(record.id),
@@ -200,7 +200,7 @@ export class BaseClient {
     })
   }
 
-  // ---- PocketBase-compatible collection() API -----------------------------
+  // ---- Base-compatible collection() API ------------------------------------
 
   /** Get or create a CollectionService for the given name/id. */
   collection(nameOrId: string): CollectionService {
@@ -269,7 +269,7 @@ export class BaseClient {
     if (options?.perPage) params.set('perPage', String(options.perPage))
 
     const qs = params.toString()
-    const path = `/api/collections/${encodeURIComponent(collection)}/records${qs ? '?' + qs : ''}`
+    const path = `/v1/collections/${encodeURIComponent(collection)}/records${qs ? '?' + qs : ''}`
     const result = await this._request<ListResult>('GET', path)
 
     this.store.setQuery(collection, options?.filter ?? '', result.items)
@@ -281,26 +281,26 @@ export class BaseClient {
     if (options?.expand) params.set('expand', options.expand)
     if (options?.fields) params.set('fields', options.fields)
     const qs = params.toString()
-    const path = `/api/collections/${encodeURIComponent(collection)}/records/${encodeURIComponent(id)}${qs ? '?' + qs : ''}`
+    const path = `/v1/collections/${encodeURIComponent(collection)}/records/${encodeURIComponent(id)}${qs ? '?' + qs : ''}`
     return this._request<BaseRecord>('GET', path)
   }
 
   async create(collection: string, data: Record<string, unknown>): Promise<BaseRecord> {
-    const path = `/api/collections/${encodeURIComponent(collection)}/records`
+    const path = `/v1/collections/${encodeURIComponent(collection)}/records`
     const record = await this._request<BaseRecord>('POST', path, data)
     this.store.applyServerUpdate(collection, 'create', record)
     return record
   }
 
   async update(collection: string, id: string, data: Record<string, unknown>): Promise<BaseRecord> {
-    const path = `/api/collections/${encodeURIComponent(collection)}/records/${encodeURIComponent(id)}`
+    const path = `/v1/collections/${encodeURIComponent(collection)}/records/${encodeURIComponent(id)}`
     const record = await this._request<BaseRecord>('PATCH', path, data)
     this.store.applyServerUpdate(collection, 'update', record)
     return record
   }
 
   async delete(collection: string, id: string): Promise<void> {
-    const path = `/api/collections/${encodeURIComponent(collection)}/records/${encodeURIComponent(id)}`
+    const path = `/v1/collections/${encodeURIComponent(collection)}/records/${encodeURIComponent(id)}`
     await this._request<void>('DELETE', path)
     this.store.applyServerUpdate(collection, 'delete', { id } as BaseRecord)
   }
@@ -312,7 +312,7 @@ export class BaseClient {
     identity: string,
     password: string,
   ): Promise<{ token: string; record: BaseRecord }> {
-    const path = `/api/collections/${encodeURIComponent(collection)}/auth-with-password`
+    const path = `/v1/collections/${encodeURIComponent(collection)}/auth-with-password`
     const result = await this._request<{ token: string; record: BaseRecord }>('POST', path, {
       identity,
       password,
@@ -329,7 +329,7 @@ export class BaseClient {
   }
 
   async refreshAuth(collection: string): Promise<{ token: string; record: BaseRecord }> {
-    const path = `/api/collections/${encodeURIComponent(collection)}/auth-refresh`
+    const path = `/v1/collections/${encodeURIComponent(collection)}/auth-refresh`
     const result = await this._request<{ token: string; record: BaseRecord }>('POST', path)
     this.authStore.save(result.token, result.record)
     return result
@@ -391,7 +391,7 @@ export class BaseClient {
   // ---- Health check -------------------------------------------------------
 
   async health(): Promise<{ code: number; message: string }> {
-    return this.send('/api/health')
+    return this.send('/v1/health')
   }
 
   // ---- Realtime convenience -----------------------------------------------

package/src/core/collection.ts

@@ -1,7 +1,7 @@
 /**
  * CollectionService -- typed CRUD + auth + realtime for a single collection.
  *
- * API-compatible with PocketBase JS SDK's RecordService, extended with
+ * API-compatible with the upstream RecordService interface, extended with
  * reactive features (subscribe/unsubscribe, optimistic writes).
  */
 
@@ -379,7 +379,7 @@ export class CollectionService {
   // ---- Internal -----------------------------------------------------------
 
   private _collectionPath(): string {
-    return `/api/collections/${encodeURIComponent(this.collectionIdOrName)}`
+    return `/v1/collections/${encodeURIComponent(this.collectionIdOrName)}`
   }
 
   private _applyOptions(params: URLSearchParams, options?: RecordQueryOptions): void {

package/src/core/index.ts

@@ -1,9 +1,12 @@
 /**
- * @hanzoai/base -- Core entry point.
+ * @hanzo/base -- Core entry point.
  *
- * Re-exports the client, collection, store, state, and realtime modules.
+ * Exposes the full Base client surface natively. No upstream package
+ * dependency — every type and helper the SDK needs lives here.
  */
 
+import { BaseClient } from './client.js'
+
 // Client
 export { BaseClient, BaseClientError, MemoryAuthStore, FileService } from './client.js'
 export type { AuthStore, AuthChangeCallback, ClientConfig, ListOptions, ListResult } from './client.js'
@@ -35,3 +38,25 @@ export type {
   RealtimeCallback,
   ConnectionCallback,
 } from './realtime.js'
+
+// Schema types — admin UI consumers
+export type { CollectionField, CollectionModel, RecordModel } from './types.js'
+
+// Auth stores — beyond the in-memory default
+export { LocalAuthStore, AsyncAuthStore } from './auth-stores.js'
+export type { BaseAuthStore } from './auth-stores.js'
+
+// Token + cookie helpers
+export {
+  getTokenPayload,
+  isTokenExpired,
+  cookieParse,
+  cookieSerialize,
+  normalizeUnknownQueryParams,
+} from './tokens.js'
+export type { CookieSerializeOptions } from './tokens.js'
+
+// Default export — matches the upstream client default. Consumers can
+// `import Base from '@hanzo/base'` and continue calling `new Base(url)`
+// exactly as they did against the upstream package.
+export default BaseClient

package/src/core/realtime.ts

@@ -157,10 +157,10 @@ export class RealtimeService {
     this._intentionalDisconnect = false
     this._setState('connecting')
 
-    const url = `${this._baseUrl}/api/realtime`
+    const url = `${this._baseUrl}/v1/realtime`
     this._eventSource = new EventSource(url)
 
-    this._eventSource.addEventListener('PB_CONNECT', (e: MessageEvent) => {
+    this._eventSource.addEventListener('CONNECT', (e: MessageEvent) => {
       try {
         const data = JSON.parse(e.data) as { clientId: string }
         this._clientId = data.clientId
@@ -240,7 +240,7 @@ export class RealtimeService {
 
     const token = this._getToken()
     try {
-      await fetch(`${this._baseUrl}/api/realtime`, {
+      await fetch(`${this._baseUrl}/v1/realtime`, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',

package/src/core/tokens.ts

@@ -0,0 +1,139 @@
+/**
+ * JWT + cookie helpers — small utilities the compat layer used to
+ * re-export from the upstream client. Implemented natively so the SDK
+ * has zero upstream dependency.
+ */
+
+/**
+ * Decode the payload of a JWT without verifying its signature.
+ * Returns `null` for malformed tokens. Safe for browser + Node use
+ * (relies only on global `atob`).
+ */
+export function getTokenPayload<T = Record<string, unknown>>(token: string): T | null {
+  if (!token) return null
+  const parts = token.split('.')
+  if (parts.length !== 3) return null
+  try {
+    const padded = parts[1].replace(/-/g, '+').replace(/_/g, '/')
+    return JSON.parse(atob(padded)) as T
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Check whether a JWT's `exp` claim has passed.
+ * `expirationThreshold` (seconds) is subtracted from `exp` to expire
+ * tokens early — set this when you want to refresh before the actual
+ * expiration. Tokens without an `exp` claim are treated as
+ * non-expiring.
+ */
+export function isTokenExpired(token: string, expirationThreshold: number = 0): boolean {
+  const payload = getTokenPayload<{ exp?: number }>(token)
+  if (!payload || typeof payload.exp !== 'number') return true
+  return payload.exp - expirationThreshold <= Date.now() / 1000
+}
+
+/**
+ * Cookie parsing — extracts a name→value map from a Set-Cookie or
+ * Cookie header value. Decodes URI-encoded values. Mirrors the
+ * `cookie` npm package's signature so it's drop-in for the upstream
+ * client's `cookieParse`.
+ */
+export function cookieParse(input: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  if (!input) return out
+  for (const segment of input.split(/;\s*/)) {
+    if (!segment) continue
+    const eq = segment.indexOf('=')
+    if (eq < 0) continue
+    const key = segment.slice(0, eq).trim()
+    let value = segment.slice(eq + 1).trim()
+    if (value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1)
+    try {
+      out[key] = decodeURIComponent(value)
+    } catch {
+      out[key] = value
+    }
+  }
+  return out
+}
+
+export interface CookieSerializeOptions {
+  encode?: (value: string) => string
+  maxAge?: number
+  domain?: string
+  path?: string
+  expires?: Date
+  httpOnly?: boolean
+  secure?: boolean
+  sameSite?: 'strict' | 'lax' | 'none' | boolean
+  priority?: 'low' | 'medium' | 'high'
+}
+
+/**
+ * Cookie serialization — builds a `Set-Cookie` header value.
+ * `encode` defaults to `encodeURIComponent`. Throws if the name or
+ * encoded value contain invalid characters.
+ */
+export function cookieSerialize(
+  name: string,
+  value: string,
+  options: CookieSerializeOptions = {},
+): string {
+  if (!/^[\w!#$%&'*+\-.^`|~]+$/.test(name)) {
+    throw new TypeError(`cookieSerialize: invalid cookie name ${JSON.stringify(name)}`)
+  }
+  const encode = options.encode ?? encodeURIComponent
+  const encoded = encode(value)
+  if (encoded && !/^[\w!#$%&'()*+\-./:<=>?@[\]^`{|}~]*$/.test(encoded)) {
+    throw new TypeError(`cookieSerialize: invalid cookie value for ${name}`)
+  }
+  const parts = [`${name}=${encoded}`]
+  if (typeof options.maxAge === 'number' && Number.isFinite(options.maxAge)) {
+    parts.push(`Max-Age=${Math.floor(options.maxAge)}`)
+  }
+  if (options.domain) parts.push(`Domain=${options.domain}`)
+  if (options.path) parts.push(`Path=${options.path}`)
+  if (options.expires) parts.push(`Expires=${options.expires.toUTCString()}`)
+  if (options.httpOnly) parts.push('HttpOnly')
+  if (options.secure) parts.push('Secure')
+  if (options.sameSite !== undefined && options.sameSite !== false) {
+    const ss = options.sameSite
+    const value =
+      ss === true
+        ? 'Strict'
+        : `${ss.charAt(0).toUpperCase()}${ss.slice(1)}`
+    parts.push(`SameSite=${value}`)
+  }
+  if (options.priority) {
+    parts.push(`Priority=${options.priority.charAt(0).toUpperCase() + options.priority.slice(1)}`)
+  }
+  return parts.join('; ')
+}
+
+/**
+ * Normalize a query-param record so values are always strings (or
+ * arrays of strings). Mirrors the upstream `normalizeUnknownQueryParams`
+ * helper used by the auto-encoding URL builder. Nullish entries are
+ * dropped; non-primitive entries are JSON-stringified.
+ */
+export function normalizeUnknownQueryParams(
+  params: Record<string, unknown> | null | undefined,
+): Record<string, string | string[]> {
+  const out: Record<string, string | string[]> = {}
+  if (!params) return out
+  for (const [key, raw] of Object.entries(params)) {
+    if (raw === undefined || raw === null) continue
+    if (Array.isArray(raw)) {
+      out[key] = raw.map((v) => (typeof v === 'string' ? v : JSON.stringify(v)))
+    } else if (typeof raw === 'string') {
+      out[key] = raw
+    } else if (typeof raw === 'number' || typeof raw === 'boolean') {
+      out[key] = String(raw)
+    } else {
+      out[key] = JSON.stringify(raw)
+    }
+  }
+  return out
+}