{"id":34531974,"url":"https://github.com/23blocks-os/frontend-sdk","last_synced_at":"2026-06-03T02:01:10.797Z","repository":{"id":329055592,"uuid":"1115515551","full_name":"23blocks-OS/frontend-sdk","owner":"23blocks-OS","description":"TypeScript SDK for 23blocks backend-as-a-service. Build apps 10x faster with modular blocks for auth, payments, CRM, e-commerce \u0026 more. React hooks + Angular services. JSON:API compliant.","archived":false,"fork":false,"pushed_at":"2026-05-31T03:43:17.000Z","size":2821,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T05:21:18.420Z","etag":null,"topics":["angular-services","api-client","authentication","baas","backend-as-a-service","crm","developer-tools","ecommerce","headless-backend","javascript","jsonapi","modular-architecture","nextjs","nodejs","open-source","react-hooks","saas","typescript-sdk"],"latest_commit_sha":null,"homepage":"https://23blocks.com/frontend-sdk","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/23blocks-OS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-13T02:21:02.000Z","updated_at":"2026-05-31T03:43:21.000Z","dependencies_parsed_at":"2026-01-19T10:14:01.508Z","dependency_job_id":"2da6858e-ccbb-4efc-9175-e9d11e4e6380","html_url":"https://github.com/23blocks-OS/frontend-sdk","commit_stats":null,"previous_names":["23blocks-os/frontend-sdk"],"tags_count":1037,"template":false,"template_full_name":null,"purl":"pkg:github/23blocks-OS/frontend-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/23blocks-OS%2Ffrontend-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/23blocks-OS%2Ffrontend-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/23blocks-OS%2Ffrontend-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/23blocks-OS%2Ffrontend-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/23blocks-OS","download_url":"https://codeload.github.com/23blocks-OS/frontend-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/23blocks-OS%2Ffrontend-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33844687,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular-services","api-client","authentication","baas","backend-as-a-service","crm","developer-tools","ecommerce","headless-backend","javascript","jsonapi","modular-architecture","nextjs","nodejs","open-source","react-hooks","saas","typescript-sdk"],"created_at":"2025-12-24T05:47:41.205Z","updated_at":"2026-06-03T02:01:10.779Z","avatar_url":"https://github.com/23blocks-OS.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e23blocks SDK\u003c/h1\u003e\n  \u003cp\u003e\u003cstrong\u003eBuild full-stack apps 10x faster with modular backend blocks\u003c/strong\u003e\u003c/p\u003e\n  \u003cp\u003eA type-safe TypeScript SDK for \u003ca href=\"https://23blocks.com\"\u003e23blocks\u003c/a\u003e backend-as-a-service. Authentication, payments, CRM, e-commerce, and 15+ more blocks ready to use.\u003c/p\u003e\n\n  \u003c!-- Status Badges --\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://www.npmjs.com/package/@23blocks/sdk\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@23blocks/sdk.svg?style=flat-square\u0026color=blue\" alt=\"npm version\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/@23blocks/sdk\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/@23blocks/sdk.svg?style=flat-square\u0026color=green\" alt=\"npm downloads\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/23blocks-OS/frontend-sdk/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/23blocks-OS/frontend-sdk/ci.yml?style=flat-square\" alt=\"CI\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/23blocks-OS/frontend-sdk/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square\" alt=\"MIT License\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\n  \u003c!-- Tech Stack Badges --\u003e\n  \u003cp\u003e\n    \u003cimg src=\"https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=flat-square\u0026logo=typescript\u0026logoColor=white\" alt=\"TypeScript\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/React-18+-61DAFB?style=flat-square\u0026logo=react\u0026logoColor=black\" alt=\"React\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Angular-16+-DD0031?style=flat-square\u0026logo=angular\u0026logoColor=white\" alt=\"Angular\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Next.js-14+-000000?style=flat-square\u0026logo=nextdotjs\u0026logoColor=white\" alt=\"Next.js\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Node.js-18+-339933?style=flat-square\u0026logo=nodedotjs\u0026logoColor=white\" alt=\"Node.js\"\u003e\n  \u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://23blocks.com/docs\"\u003eDocumentation\u003c/a\u003e \u0026bull;\n    \u003ca href=\"https://23blocks.com\"\u003eWebsite\u003c/a\u003e \u0026bull;\n    \u003ca href=\"https://github.com/23blocks-OS/frontend-sdk/issues\"\u003eIssues\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\n## Features\n\n- **Modular architecture** - Install only the blocks you need\n- **Framework agnostic** - Core packages work with any JavaScript framework\n- **First-class TypeScript** - Full type safety with comprehensive type definitions\n- **Angular \u0026 React bindings** - Native integrations with RxJS Observables and React hooks\n- **JSON:API compliant** - Built on the [JSON:API v1.0](https://jsonapi.org/) specification\n- **Debug logging** - Built-in request/response logging for development\n- **Request tracing** - Automatic request IDs for debugging and support\n- **Automatic retries** - Exponential backoff with jitter for transient failures\n- **Interceptors** - Hook into request/response lifecycle for cross-cutting concerns\n\n## Why 23blocks?\n\nStop rebuilding the same backend features for every project. 23blocks provides production-ready building blocks:\n\n| Challenge | 23blocks Solution |\n|-----------|------------------|\n| Building auth from scratch | Ready-to-use authentication with MFA, OAuth, roles, API keys |\n| Weeks on CRUD operations | Pre-built blocks for CRM, products, content, forms |\n| Complex payment integrations | Wallet and sales blocks with transaction support |\n| Framework lock-in | Works with React, Angular, Next.js, Vue, or vanilla JS |\n| Inconsistent API responses | JSON:API v1.0 compliant, predictable data structures |\n| Debugging production issues | Built-in request tracing with unique IDs |\n\n**Perfect for building:** SaaS applications \u0026bull; E-commerce platforms \u0026bull; Marketplaces \u0026bull; Internal tools \u0026bull; Mobile app backends \u0026bull; Multi-tenant systems\n\n## The LEGO Philosophy: One SDK, Any Backend\n\nThis SDK is built on **contracts, not dependencies**. Use 23blocks services or bring your own backend — as long as it speaks the same language, it just works.\n\n```typescript\n// Use 23blocks managed services\nconst client = create23BlocksClient({\n  urls: { authentication: 'https://api.23blocks.com' },\n  apiKey: 'your-api-key',\n});\n\n// OR use your own backend\nconst client = create23BlocksClient({\n  urls: { authentication: 'https://your-api.com' },\n  apiKey: 'your-api-key',\n});\n\n// Same SDK. Same code. Same types.\n// Your backend just needs to implement the JSON:API contract.\n```\n\n| Approach | Description |\n|----------|-------------|\n| **JSON:API Contract** | Every endpoint follows the [JSON:API specification](https://jsonapi.org/). Standardized request/response formats mean predictable, reliable integrations. |\n| **Swap Any Backend** | Using 23blocks Auth today but want to build your own? Implement the contract, point the SDK at your server, done. Zero frontend changes. |\n| **No Vendor Lock-in** | The contract is open. The SDK is open. Your architecture remains yours — we're just making it easier to build. |\n\n\u003e **Build your own backend?** The contract defines endpoints, models, and response formats. Implement it in Rails, Node, Go, Python, or any language you prefer. See our [Contract Specification](https://23blocks.com/frontend-sdk) for details.\n\n## Comparison\n\n| Feature | 23blocks | Firebase | Supabase | Custom Backend |\n|---------|:--------:|:--------:|:--------:|:--------------:|\n| Type-safe SDK | ✅ | ⚠️ Partial | ✅ | ❌ Build yourself |\n| Modular architecture | ✅ 18+ blocks | ❌ Monolithic | ⚠️ Limited | ❌ Build yourself |\n| React hooks | ✅ Native | ⚠️ Community | ✅ | ❌ Build yourself |\n| Angular services | ✅ Native RxJS | ⚠️ Community | ❌ | ❌ Build yourself |\n| JSON:API compliant | ✅ | ❌ | ❌ | ❌ Build yourself |\n| Request tracing | ✅ Built-in | ❌ | ❌ | ❌ Build yourself |\n| Self-hostable | ✅ | ❌ | ✅ | ✅ |\n| Bring your own backend | ✅ Contract-based | ❌ Locked | ❌ Locked | N/A |\n| Open source SDK | ✅ MIT | ✅ | ✅ | N/A |\n\n## Quick Start\n\n```bash\nnpm install @23blocks/sdk\n```\n\n```typescript\nimport { create23BlocksClient } from '@23blocks/sdk';\n\n// Create client - that's it!\nconst client = create23BlocksClient({\n  urls: { authentication: 'https://api.yourapp.com' },\n  apiKey: 'your-api-key',\n});\n\n// Sign in - tokens are stored automatically\nawait client.auth.signIn({ email: 'user@example.com', password: 'password' });\n\n// All subsequent requests include auth automatically\nconst products = await client.products.products.list();\nconst user = await client.auth.getCurrentUser();\n\n// Sign out - tokens are cleared automatically\nawait client.auth.signOut();\n```\n\n\u003e **Works with any compatible backend!** Use [23blocks managed services](https://23blocks.com) for instant setup, or implement the [JSON:API contract](https://23blocks.com/frontend-sdk) on your own servers.\n\nSee [Installation Guide](./docs/installation.md) for detailed options.\n\n## Debug Mode\n\nEnable debug logging to see all requests and responses in your console:\n\n```typescript\nimport { create23BlocksClient } from '@23blocks/sdk';\n\nconst client = create23BlocksClient({\n  urls: { authentication: 'https://api.yourapp.com' },\n  apiKey: 'your-api-key',\n  debug: true,  // Enable debug logging\n});\n```\n\nConsole output:\n```\n[23blocks] POST /auth/sign_in [req_m5abc_xyz123]\n[23blocks] → Headers: { \"x-api-key\": \"***\", \"content-type\": \"application/json\" }\n[23blocks] → Body: { \"email\": \"user@example.com\", \"password\": \"***\" }\n[23blocks] ← 200 OK (145ms) [req_m5abc_xyz123]\n```\n\n## Error Handling with Request Tracing\n\nEvery error includes a unique request ID for easy debugging:\n\n```typescript\nimport { isBlockErrorException } from '@23blocks/contracts';\n\ntry {\n  await client.auth.signIn({ email: 'user@example.com', password: 'wrong' });\n} catch (error) {\n  if (isBlockErrorException(error)) {\n    console.log('Request ID:', error.requestId);  // \"req_m5abc_xyz123\"\n    console.log('Duration:', error.duration);      // 145 (ms)\n    console.log('Message:', error.message);        // \"Invalid credentials\"\n\n    // Send to support: \"Please check request req_m5abc_xyz123\"\n  }\n}\n```\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Installation](./docs/installation.md) | Full SDK vs individual packages |\n| [Angular](./docs/angular.md) | Setup with Injectable services and RxJS |\n| [Next.js / React](./docs/nextjs.md) | Setup with hooks and context |\n| [Vanilla TypeScript](./docs/vanilla.md) | Framework-agnostic usage |\n\n## Available Packages\n\n### Core Infrastructure\n\n| Package | Description |\n|---------|-------------|\n| `@23blocks/contracts` | Core types and interfaces |\n| `@23blocks/jsonapi-codec` | JSON:API encoder/decoder |\n| `@23blocks/transport-http` | HTTP transport layer |\n\n### Feature Blocks\n\n| Package | Description |\n|---------|-------------|\n| `@23blocks/block-authentication` | Auth, users, roles, API keys |\n| `@23blocks/block-search` | Full-text search, favorites |\n| `@23blocks/block-products` | Product catalog, categories, variants |\n| `@23blocks/block-crm` | Contacts, organizations, deals |\n| `@23blocks/block-content` | CMS content, pages, media |\n| `@23blocks/block-geolocation` | Addresses, places, geocoding |\n| `@23blocks/block-conversations` | Messaging, threads, notifications |\n| `@23blocks/block-files` | File uploads, storage |\n| `@23blocks/block-forms` | Form builder, submissions |\n| `@23blocks/block-assets` | Asset management, tracking |\n| `@23blocks/block-campaigns` | Marketing campaigns, audiences |\n| `@23blocks/block-company` | Company settings, branding |\n| `@23blocks/block-rewards` | Loyalty programs, points |\n| `@23blocks/block-sales` | Orders, invoices, payments |\n| `@23blocks/block-wallet` | Digital wallet, transactions |\n| `@23blocks/block-jarvis` | AI assistant integration |\n| `@23blocks/block-onboarding` | User onboarding flows |\n| `@23blocks/block-university` | Learning management, courses |\n\n### Framework Bindings\n\n| Package | Description |\n|---------|-------------|\n| `@23blocks/angular` | Angular services with RxJS Observables |\n| `@23blocks/react` | React hooks and context provider |\n| `@23blocks/sdk` | Meta-package with all blocks |\n\n### Testing\n\n| Package | Description |\n|---------|-------------|\n| `@23blocks/testing` | Mock transport, fixtures, and assertion helpers |\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│  Framework Bindings                                         │\n│  ┌──────────────────┐  ┌──────────────────┐                │\n│  │ @23blocks/angular│  │ @23blocks/react  │                │\n│  │ (RxJS Observables)  │ (hooks, context) │                │\n│  └────────┬─────────┘  └────────┬─────────┘                │\n└───────────┼─────────────────────┼──────────────────────────┘\n            │                     │\n┌───────────▼─────────────────────▼──────────────────────────┐\n│  Blocks (Promise-based, framework agnostic)                │\n│  ┌────────────────┐ ┌────────────────┐ ┌────────────────┐  │\n│  │ authentication │ │    search      │ │   products     │  │\n│  └────────────────┘ └────────────────┘ └────────────────┘  │\n│  ┌────────────────┐ ┌────────────────┐ ┌────────────────┐  │\n│  │      crm       │ │    content     │ │    + more      │  │\n│  └────────┬───────┘ └────────┬───────┘ └────────┬───────┘  │\n└───────────┼──────────────────┼──────────────────┼──────────┘\n            │                  │                  │\n┌───────────▼──────────────────▼──────────────────▼──────────┐\n│  Core Infrastructure                                        │\n│  ┌────────────┐ ┌──────────────┐ ┌──────────────────┐      │\n│  │ contracts  │ │jsonapi-codec │ │  transport-http  │      │\n│  └────────────┘ └──────────────┘ └──────────────────┘      │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Requirements\n\n- Node.js \u003e= 18.0.0\n- TypeScript \u003e= 5.0 (for TypeScript users)\n- Angular \u003e= 10 (for `@23blocks/angular`)\n- React \u003e= 18 (for `@23blocks/react`)\n\n## Contributing\n\nWe welcome contributions! Please see our [Development Guide](./DEVELOPMENT.md) for details.\n\n## Support the Project\n\nIf 23blocks SDK helps you build faster, consider giving us a star! It helps others discover the project and motivates us to keep improving.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/23blocks-OS/frontend-sdk/stargazers\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/23blocks-OS/frontend-sdk?style=social\" alt=\"GitHub stars\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## License\n\n[MIT](./LICENSE) - Copyright (c) 2024 23blocks\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F23blocks-os%2Ffrontend-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F23blocks-os%2Ffrontend-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F23blocks-os%2Ffrontend-sdk/lists"}