@apito-io/js-admin-sdk 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Apito
+
+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,351 @@
+# Apito Admin JavaScript SDK
+
+[![npm version](https://badge.fury.io/js/%40apito-io%2Fjs-admin-sdk.svg)](https://badge.fury.io/js/%40apito-io%2Fjs-admin-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A comprehensive JavaScript SDK for communicating with Apito GraphQL API endpoints. This SDK provides both type-safe and flexible interfaces for interacting with Apito's backend services.
+
+## 🚀 Features
+
+- ✅ **Complete SDK Implementation**: Full implementation matching the Go SDK
+- ✅ **Type-Safe Operations**: Generic typed methods for better development experience
+- ✅ **GraphQL-Based**: Native GraphQL communication with Apito backend
+- ✅ **Authentication Ready**: API key and tenant-based authentication
+- ✅ **Promise-Based**: Modern async/await support
+- ✅ **Comprehensive Error Handling**: Detailed error responses and GraphQL error support
+- ✅ **Plugin-Ready**: Perfect for Node.js applications and microservices
+- ✅ **Production Ready**: Battle-tested patterns and error handling
+
+## 📦 Installation
+
+```bash
+npm install @apito-io/js-admin-sdk
+```
+
+or
+
+```bash
+yarn add @apito-io/js-admin-sdk
+```
+
+## 🎯 Quick Start
+
+```javascript
+import { ApitoClient } from '@apito-io/js-admin-sdk';
+
+// Create a new client
+const client = new ApitoClient({
+  baseURL: 'https://api.apito.io/graphql',
+  apiKey: 'your-api-key-here',
+  timeout: 30000,
+});
+
+// Create a new todo
+async function createTodo() {
+  const todoData = {
+    title: 'Learn Apito SDK',
+    description: 'Complete the SDK tutorial',
+    status: 'todo',
+    priority: 'high',
+  };
+
+  const request = {
+    model: 'todos',
+    payload: todoData,
+  };
+
+  const todo = await client.createNewResource(request);
+  console.log('Created todo:', todo.id);
+}
+```
+
+## 📚 API Reference
+
+### Client Configuration
+
+```javascript
+const client = new ApitoClient({
+  baseURL: 'https://api.apito.io/graphql',  // Your Apito GraphQL endpoint
+  apiKey: 'your-api-key-here',             // X-APITO-KEY header value
+  timeout: 30000,                          // Request timeout in milliseconds
+  tenantId: 'your-tenant-id',              // Optional tenant ID
+  httpClient: {                            // Optional axios configuration
+    maxRedirects: 5,
+    // ... other axios config
+  },
+});
+```
+
+### Core Methods
+
+#### `getSingleResource(model, id, singlePageData?)`
+Get a single resource by model and ID.
+
+```javascript
+const todo = await client.getSingleResource('todos', '123');
+console.log(todo.data.title);
+```
+
+#### `searchResources(model, filter?, aggregate?)`
+Search resources in a model with filtering. Only these `filter` fields are sent to GraphQL (same as the Go internal SDK): `_key`, `page`, `limit`, `where`, `search`. The `aggregate` argument is reserved for a future schema option and is not sent today.
+
+```javascript
+const results = await client.searchResources('todos', {
+  where: { status: 'todo' },
+  limit: 10,
+  page: 1,
+});
+console.log(`Found ${results.count} todos`);
+```
+
+#### `createNewResource(request)`
+Create a new resource.
+
+```javascript
+const newTodo = await client.createNewResource({
+  model: 'todos',
+  payload: {
+    title: 'New Task',
+    status: 'todo',
+  },
+  connect: { user: 'user-123' }, // Optional relations
+});
+```
+
+#### `updateResource(request)`
+Update an existing resource.
+
+```javascript
+const updatedTodo = await client.updateResource({
+  model: 'todos',
+  id: '123',
+  payload: {
+    status: 'completed',
+    completed_at: new Date().toISOString(),
+  },
+  connect: { tags: ['urgent'] }, // Add relations
+  disconnect: { tags: ['low-priority'] }, // Remove relations
+});
+```
+
+#### `deleteResource(model, id)`
+Delete a resource.
+
+```javascript
+await client.deleteResource('todos', '123');
+```
+
+#### `getRelationDocuments(id, connection)`
+Get related documents.
+
+```javascript
+const relatedUsers = await client.getRelationDocuments('todo-123', {
+  model: 'users',
+  field: 'assigned_to',
+});
+```
+
+### Typed Operations
+
+For type-safe operations, use the `TypedOperations` class:
+
+```javascript
+import { TypedOperations } from '@apito-io/js-admin-sdk';
+
+const typed = new TypedOperations(client);
+
+// Define your types
+interface Todo {
+  id: string;
+  title: string;
+  description: string;
+  status: 'todo' | 'in_progress' | 'completed';
+  priority: 'low' | 'medium' | 'high';
+}
+
+// Type-safe operations
+const typedTodo = await typed.createNewResourceTyped<Todo>({
+  model: 'todos',
+  payload: {
+    title: 'Type-safe todo',
+    status: 'todo',
+    priority: 'high',
+  },
+});
+
+// TypeScript will infer the correct type
+console.log(typedTodo.data.title); // string
+console.log(typedTodo.data.status); // 'todo' | 'in_progress' | 'completed'
+```
+
+### Error Handling
+
+The SDK provides comprehensive error handling:
+
+```javascript
+import { ApitoError, ValidationError, GraphQLError } from '@apito-io/js-admin-sdk';
+
+try {
+  const result = await client.getSingleResource('todos', 'invalid-id');
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error('Validation error:', error.message);
+  } else if (error instanceof GraphQLError) {
+    console.error('GraphQL error:', error.graphQLErrors);
+  } else if (error instanceof ApitoError) {
+    console.error('API error:', error.statusCode, error.message);
+  } else {
+    console.error('Unknown error:', error);
+  }
+}
+```
+
+### Environment Variables
+
+You can configure the client using environment variables:
+
+```bash
+# Required
+APITO_BASE_URL=https://api.apito.io/graphql
+APITO_API_KEY=your-production-api-key
+
+# Optional
+APITO_TENANT_ID=your-tenant-id
+APITO_TIMEOUT=30000
+```
+
+```javascript
+import { ApitoClient } from '@apito-io/js-admin-sdk';
+
+const client = new ApitoClient({
+  baseURL: process.env.APITO_BASE_URL,
+  apiKey: process.env.APITO_API_KEY,
+  tenantId: process.env.APITO_TENANT_ID,
+  timeout: parseInt(process.env.APITO_TIMEOUT || '30000'),
+});
+```
+
+## 🧪 Examples
+
+### Basic CRUD Operations
+
+```javascript
+import { ApitoClient } from '@apito-io/js-admin-sdk';
+
+const client = new ApitoClient({
+  baseURL: 'https://api.apito.io/graphql',
+  apiKey: 'your-api-key',
+});
+
+// Create
+const user = await client.createNewResource({
+  model: 'users',
+  payload: {
+    name: 'John Doe',
+    email: 'john@example.com',
+  },
+});
+
+// Read
+const fetchedUser = await client.getSingleResource('users', user.id);
+
+// Update
+const updatedUser = await client.updateResource({
+  model: 'users',
+  id: user.id,
+  payload: {
+    name: 'John Updated',
+  },
+});
+
+// Delete
+await client.deleteResource('users', user.id);
+```
+
+### Advanced Filtering
+
+```javascript
+// Complex search with multiple filters
+const results = await client.searchResources('products', {
+  where: {
+    AND: [
+      { price: { gte: 100 } },
+      { category: { in: ['electronics', 'books'] } },
+      { status: 'active' },
+    ],
+  },
+  search: 'laptop',
+  limit: 20,
+  page: 1,
+});
+```
+
+### Batch Operations
+
+```javascript
+// Create multiple records
+const todos = [
+  { title: 'Task 1', status: 'todo' },
+  { title: 'Task 2', status: 'todo' },
+  { title: 'Task 3', status: 'todo' },
+];
+
+const createdTodos = await Promise.all(
+  todos.map(todo => client.createNewResource({
+    model: 'todos',
+    payload: todo,
+  }))
+);
+```
+
+## Parity with the Go internal SDK
+
+This client mirrors the Go `go-internal-sdk` package and the `InternalSDKOperation` interface from `github.com/apito-io/types`.
+
+- **Tenant header:** In Go, set `context.WithValue(ctx, "tenant_id", id)` before calls. In JavaScript, set `tenantId` on `ClientConfig`, or rely on `generateTenantToken`, which sends `X-Apito-Tenant-ID` for that mutation.
+- **GraphQL errors:** The Go client returns `(response, err)` when the response includes `errors`. This SDK throws `GraphQLError` with `graphQLErrors` and the full payload on `response`; use `error.partialData` to read `data` when the server returns partial success.
+- **`searchResources` filter:** Only `_key`, `page`, `limit`, `where`, and `search` are forwarded. Extra keys are ignored so unknown GraphQL variables cannot break the request.
+- **`TypedOperations`:** `data` is deep-cloned via `JSON.parse(JSON.stringify(...))`, matching the Go SDK’s marshal/unmarshal approach for typed document `data`.
+
+## 🏗️ Development
+
+### Building from Source
+
+```bash
+git clone https://github.com/apito-io/js-admin-sdk.git
+cd js-admin-sdk
+npm install
+npm run build
+```
+
+### Running Tests
+
+```bash
+npm test
+```
+
+### Running Examples
+
+```bash
+cd examples/basic
+npm install
+npm start
+```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🔗 Links
+
+- [Apito Documentation](https://docs.apito.io)
+- [npm Package](https://www.npmjs.com/package/@apito-io/js-admin-sdk)
+- [GitHub Repository](https://github.com/apito-io/js-admin-sdk)
+- [Issues](https://github.com/apito-io/js-admin-sdk/issues)
+
+## 🆘 Support
+
+- 📧 Email: support@apito.io
+- 💬 Discord: [Join our community](https://discord.gg/apito)
+- 📖 Documentation: [docs.apito.io](https://docs.apito.io)
+- 🐛 Bug Reports: [GitHub Issues](https://github.com/apito-io/js-admin-sdk/issues)

package/dist/index.d.mts

@@ -0,0 +1,218 @@
+/**
+ * Type definitions for the Apito JavaScript SDK
+ */
+interface MetaField {
+    created_at: string;
+    updated_at: string;
+    status: string;
+    revision?: string;
+    revision_at?: string;
+    root_revision_id?: string;
+}
+interface DefaultDocumentStructure {
+    _key?: string;
+    _id?: string;
+    data: any;
+    meta?: MetaField;
+    id: string;
+    expire_at?: string | number;
+    relation_doc_id?: string;
+    last_revision_doc_id?: string;
+    type?: string;
+    tenant_id?: string;
+    tenant_model?: string;
+}
+interface SearchResult {
+    results: DefaultDocumentStructure[];
+    count: number;
+}
+interface TypedDocumentStructure<T> {
+    _key?: string;
+    _id?: string;
+    data: T;
+    meta?: MetaField;
+    id: string;
+    expire_at?: string | number;
+    relation_doc_id?: string;
+    last_revision_doc_id?: string;
+    type?: string;
+    tenant_id?: string;
+    tenant_model?: string;
+}
+interface TypedSearchResult<T> {
+    results: TypedDocumentStructure<T>[];
+    count: number;
+}
+interface Filter {
+    page?: number;
+    offset?: number;
+    limit?: number;
+    order?: string;
+    min?: number;
+    max?: number;
+    category?: string;
+}
+interface GraphQLErrorLocation {
+    line: number;
+    column: number;
+}
+interface GraphQLResponse {
+    data?: any;
+    errors?: GraphQLError[];
+}
+interface CreateAndUpdateRequest {
+    id?: string;
+    model: string;
+    payload: any;
+    connect?: Record<string, any>;
+    disconnect?: Record<string, any>;
+    singlePageData?: boolean;
+    forceUpdate?: boolean;
+}
+interface ClientConfig {
+    baseURL: string;
+    apiKey: string;
+    timeout?: number;
+    httpClient?: any;
+    tenantId?: string;
+}
+interface RequestOptions {
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+interface SearchOptions {
+    limit?: number;
+    page?: number;
+    offset?: number;
+    where?: Record<string, any>;
+    search?: string;
+    sort?: Record<string, 1 | -1>;
+}
+interface ConnectionOptions {
+    model: string;
+    filter?: SearchOptions;
+}
+interface InjectedDBOperationInterface {
+    generateTenantToken(token: string, tenantId: string): Promise<string>;
+    getSingleResource(model: string, id: string, singlePageData?: boolean): Promise<DefaultDocumentStructure>;
+    searchResources(model: string, filter?: Record<string, any>, aggregate?: boolean): Promise<SearchResult>;
+    getRelationDocuments(id: string, connection: Record<string, any>): Promise<SearchResult>;
+    createNewResource(request: CreateAndUpdateRequest): Promise<DefaultDocumentStructure>;
+    updateResource(request: CreateAndUpdateRequest): Promise<DefaultDocumentStructure>;
+    deleteResource(model: string, id: string): Promise<void>;
+    debug(stage: string, ...data: any[]): Promise<any>;
+}
+declare class ApitoError extends Error {
+    code?: string;
+    statusCode?: number;
+    details?: any;
+    constructor(message: string, code?: string, statusCode?: number, details?: any);
+}
+interface GraphQLError {
+    message: string;
+    locations?: GraphQLErrorLocation[];
+    path?: (string | number)[];
+    extensions?: Record<string, any>;
+}
+declare class GraphQLError extends ApitoError {
+    graphQLErrors: GraphQLError[];
+    response?: any;
+    constructor(message: string, graphQLErrors: GraphQLError[], response?: any);
+    get partialData(): any;
+}
+declare class ValidationError extends ApitoError {
+    field?: string;
+    constructor(message: string, field?: string);
+}
+
+/**
+ * Apito SDK Client - JavaScript implementation matching the Go SDK
+ */
+declare class ApitoClient implements InjectedDBOperationInterface {
+    private httpClient;
+    private baseURL;
+    private apiKey;
+    private tenantId?;
+    constructor(config: ClientConfig);
+    /**
+     * Execute a GraphQL query or mutation
+     */
+    private executeGraphQL;
+    /**
+     * Generate a new tenant token for the specified tenant ID
+     */
+    generateTenantToken(token: string, tenantId: string): Promise<string>;
+    /**
+     * Get a single resource by model and ID
+     */
+    getSingleResource(model: string, id: string, singlePageData?: boolean): Promise<DefaultDocumentStructure>;
+    /**
+     * Search resources in a model
+     */
+    searchResources(model: string, filter?: Record<string, any>, aggregate?: boolean): Promise<SearchResult>;
+    /**
+     * Get related documents
+     */
+    getRelationDocuments(id: string, connection: Record<string, any>): Promise<SearchResult>;
+    /**
+     * Create a new resource
+     */
+    createNewResource(request: CreateAndUpdateRequest): Promise<DefaultDocumentStructure>;
+    /**
+     * Update an existing resource
+     */
+    updateResource(request: CreateAndUpdateRequest): Promise<DefaultDocumentStructure>;
+    /**
+     * Delete a resource by model and ID
+     */
+    deleteResource(model: string, id: string): Promise<void>;
+    /**
+     * Debug is used to debug the plugin, you can pass data here to debug the plugin
+     */
+    debug(stage: string, ...data: any[]): Promise<any>;
+}
+/**
+ * Factory function to create a new Apito client
+ */
+declare function createClient(config: ClientConfig): ApitoClient;
+
+/**
+ * Typed operations wrapper for the Apito SDK
+ * Provides type-safe methods for working with typed data
+ */
+declare class TypedOperations {
+    private client;
+    constructor(client: ApitoClient);
+    private static toTypedDocument;
+    /**
+     * Get a single resource with type safety
+     */
+    getSingleResourceTyped<T>(model: string, id: string, singlePageData?: boolean): Promise<TypedDocumentStructure<T>>;
+    /**
+     * Search resources with type safety
+     */
+    searchResourcesTyped<T>(model: string, filter?: Record<string, any>, aggregate?: boolean): Promise<TypedSearchResult<T>>;
+    /**
+     * Get related documents with type safety
+     */
+    getRelationDocumentsTyped<T>(id: string, connection: Record<string, any>): Promise<TypedSearchResult<T>>;
+    /**
+     * Create a new resource with type safety
+     */
+    createNewResourceTyped<T>(request: CreateAndUpdateRequest): Promise<TypedDocumentStructure<T>>;
+    /**
+     * Update a resource with type safety
+     */
+    updateResourceTyped<T>(request: CreateAndUpdateRequest): Promise<TypedDocumentStructure<T>>;
+}
+
+/**
+ * Apito JavaScript internal SDK version (kept in sync with package.json for releases)
+ */
+declare const Version = "2.0.0";
+/**
+ * GetVersion returns the current version of the SDK
+ */
+declare function getVersion(): string;
+
+export { ApitoClient, ApitoError, type ClientConfig, type ConnectionOptions, type CreateAndUpdateRequest, type DefaultDocumentStructure, type Filter, GraphQLError, type GraphQLErrorLocation, type GraphQLResponse, type InjectedDBOperationInterface, type MetaField, type RequestOptions, type SearchOptions, type SearchResult, type TypedDocumentStructure, TypedOperations, type TypedSearchResult, ValidationError, Version, createClient, ApitoClient as default, getVersion };