@snackbase/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial release of SnackBase SDK for JavaScript/TypeScript
+
+### Features
+- **Core Client**: `SnackBaseClient` with configuration validation
+- **HTTP Client**: Fetch-based HTTP client with interceptors
+- **Authentication**: Email/password, OAuth, SAML, and API key authentication
+- **Services**: 17+ service classes for all SnackBase resources
+  - Accounts, Users, Collections, Records
+  - Roles, Collection Rules (Permission System V2)
+  - Groups, Invitations, Macros
+  - API Keys, Audit Logs, Dashboard, Admin
+  - Email Templates, Files
+- **Real-Time**: WebSocket/SSE support with automatic reconnection
+- **Query Builder**: Fluent API for complex queries
+- **React Integration**: Context provider and hooks
+  - `useAuth`, `useQuery`, `useRecord`, `useMutation`, `useSubscription`
+- **Type Safety**: Complete TypeScript definitions
+- **Error Handling**: Typed error hierarchy
+- **Storage Abstraction**: Platform-agnostic storage backends
+- **Logging**: Structured logging system with configurable levels
+
+### Package Exports
+- `@snackbase/sdk` - Core SDK
+- `@snackbase/sdk/react` - React integration
+
+### Build Output
+- ESM (`.mjs`) - 14.87 KB gzipped
+- CommonJS (`.js`)
+- TypeScript declarations (`.d.ts`)
+
+## [0.1.0] - 2025-01-XX
+
+### Added
+- Initial beta release
+- Complete Phase 1-4 implementation
+- Core SDK features
+- React hooks
+- Real-time subscriptions
+- Query builder
+- 231 tests passing
+
+## [Future Releases]
+
+### Planned
+- Integration tests with test server
+- Performance benchmarks
+- Request deduplication
+- Advanced caching strategies
+- Vue 3 integration
+- Angular integration
+- Svelte integration

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SnackBase
+
+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,287 @@
+# SnackBase SDK
+
+[![npm version](https://badge.fury.io/js/%40snackbase%2Fsdk.svg)](https://www.npmjs.com/package/@snackbase/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://github.com/snackbase/snackbase-js/workflows/CI/badge.svg)](https://github.com/snackbase/snackbase-js/actions)
+
+The official JavaScript/TypeScript SDK for [SnackBase](https://snackbase.dev) - a powerful backend-as-a-service platform.
+
+## Features
+
+- **Type-Safe**: Built with TypeScript for full type safety and excellent developer experience
+- **Authentication**: Support for JWT tokens, OAuth, SAML, and API keys
+- **Real-Time**: WebSocket and SSE support for real-time data synchronization
+- **React Integration**: Dedicated React hooks and context for seamless integration
+- **Query Builder**: Fluent API for building complex queries with filtering, sorting, and pagination
+- **Platform Agnostic**: Works in browsers, React Native, and Node.js
+- **Lightweight**: Only 14.87 KB gzipped for the core SDK
+
+## Installation
+
+```bash
+# npm
+npm install @snackbase/sdk
+
+# yarn
+yarn add @snackbase/sdk
+
+# pnpm
+pnpm add @snackbase/sdk
+```
+
+### React Integration
+
+```bash
+# npm
+npm install @snackbase/sdk react
+
+# yarn
+yarn add @snackbase/sdk react
+
+# pnpm
+pnpm add @snackbase/sdk react
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { SnackBaseClient } from "@snackbase/sdk";
+
+// Initialize the client
+const client = new SnackBaseClient({
+  baseUrl: "https://your-project.snackbase.dev",
+  apiKey: "your-api-key", // Optional for public access
+});
+
+// Authenticate with email/password
+const auth = await client.auth.authenticateWithPassword({
+  email: "user@example.com",
+  password: "password123",
+});
+
+console.log("Logged in as:", auth.user.email);
+
+// List records from a collection
+const records = await client.records.list("posts", {
+  filter: { status: "published" },
+  sort: "-createdAt",
+});
+
+// Subscribe to real-time updates
+client.realtime.subscribe("posts", (event) => {
+  console.log("New event:", event.action, event.record);
+});
+```
+
+### React Integration
+
+```tsx
+import { SnackBaseProvider, useAuth, useRecord } from "@snackbase/sdk/react";
+
+function App() {
+  return (
+    <SnackBaseProvider
+      baseUrl="https://your-project.snackbase.dev"
+      apiKey="your-api-key"
+    >
+      <Posts />
+    </SnackBaseProvider>
+  );
+}
+
+function Posts() {
+  const { user, login, logout } = useAuth();
+  const { data: posts, loading } = useRecord("posts", {
+    filter: { status: "published" },
+  });
+
+  if (!user) {
+    return <button onClick={() => login(email, password)}>Login</button>;
+  }
+
+  return (
+    <div>
+      <button onClick={logout}>Logout</button>
+      {loading ? <p>Loading...</p> : <PostList posts={posts?.items} />}
+    </div>
+  );
+}
+```
+
+## Documentation
+
+- [Getting Started Guide](./docs/getting-started.md)
+- [Authentication Guide](./docs/authentication.md)
+- [Real-Time Features](./docs/realtime.md)
+- [React Integration](./docs/react-integration.md)
+- [API Reference](./docs/api-reference.md)
+- [Migration Guides](./docs/migration/)
+
+## Platform Support
+
+| Platform                                | Support |
+| --------------------------------------- | ------- |
+| Browser (Chrome, Firefox, Safari, Edge) | ✅ Full |
+| React Native                            | ✅ Full |
+| Node.js                                 | ✅ Full |
+| Next.js                                 | ✅ Full |
+| Vue/Nuxt                                | ✅ Full |
+
+## Authentication Methods
+
+| Method             | Description                                        |
+| ------------------ | -------------------------------------------------- |
+| **Email/Password** | Traditional authentication with email and password |
+| **OAuth**          | Sign in with Google, GitHub, etc.                  |
+| **SAML**           | Enterprise SSO support                             |
+| **API Key**        | Server-to-server authentication                    |
+
+## Core Services
+
+The SDK provides 17+ services for interacting with SnackBase:
+
+- `client.auth` - Authentication and user management
+- `client.users` - User CRUD operations
+- `client.accounts` - Account management
+- `client.collections` - Collection/schema management
+- `client.records` - Dynamic record operations (CRUD, queries)
+- `client.roles` - Role-based access control
+- `client.groups` - Group management
+- `client.invitations` - User invitations
+- `client.macros` - Macro operations
+- `client.apiKeys` - API key management
+- `client.auditLogs` - Audit log access
+- `client.dashboard` - Dashboard metrics
+- `client.admin` - Admin operations
+- `client.emailTemplates` - Email template management
+- `client.files` - File upload/download
+- `client.realtime` - Real-time subscriptions
+- `client.query` - Query builder
+
+## Query Builder
+
+Build complex queries with a fluent API:
+
+```typescript
+const results = await client
+  .query("posts")
+  .select("id", "title", "author.name")
+  .expand("author", "comments")
+  .filter("status", "=", "published")
+  .filter("createdAt", ">", "2024-01-01")
+  .sort("createdAt", "desc")
+  .page(1)
+  .perPage(20)
+  .execute();
+```
+
+## Real-Time Subscriptions
+
+Subscribe to record changes in real-time:
+
+```typescript
+// Subscribe to a collection
+const unsubscribe = client.realtime.subscribe("posts", (event) => {
+  switch (event.action) {
+    case "create":
+      console.log("New post created:", event.record);
+      break;
+    case "update":
+      console.log("Post updated:", event.record);
+      break;
+    case "delete":
+      console.log("Post deleted:", event.record);
+      break;
+  }
+});
+
+// Unsubscribe when done
+unsubscribe();
+```
+
+## Error Handling
+
+The SDK provides typed errors for comprehensive error handling:
+
+```typescript
+import {
+  SnackBaseError,
+  AuthenticationError,
+  ValidationError,
+  NetworkError,
+} from "@snackbase/sdk";
+
+try {
+  await client.records.create("posts", data);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error("Validation failed:", error.fields);
+  } else if (error instanceof AuthenticationError) {
+    console.error("Authentication failed:", error.message);
+  } else if (error instanceof NetworkError) {
+    console.error("Network error:", error.message);
+  }
+}
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import type { User, Post, Comment } from "@snackbase/sdk";
+
+// Type-safe record operations
+const post: Post = await client.records.get<Post>("posts", "record-id");
+
+// Type-safe auth state
+const user: User = await client.auth.getCurrentUser();
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/snackbase/snackbase-js.git
+cd snackbase-js
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode
+npm run dev
+```
+
+## Bundle Size
+
+- Core SDK: **14.87 KB** (gzipped)
+- React Integration: **1.42 KB** (gzipped)
+- Total: **16.29 KB** (gzipped)
+
+## License
+
+MIT © [SnackBase](https://snackbase.dev)
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
+
+## Support
+
+- Documentation: [https://docs.snackbase.dev](https://docs.snackbase.dev)
+- GitHub Issues: [https://github.com/snackbase/snackbase-js/issues](https://github.com/snackbase/snackbase-js/issues)
+- Discord: [https://discord.gg/snackbase](https://discord.gg/snackbase)
+
+## Related Projects
+
+- [SnackBase](https://snackbase.dev) - The official SnackBase platform
+- [snackbase-python](https://github.com/snackbase/snackbase-python) - Python SDK
+- [snackbase-go](https://github.com/snackbase/snackbase-go) - Go SDK