@centrali-io/centrali-sdk 2.0.0 → 2.0.2

package/README.md

@@ -0,0 +1,197 @@
+# Centrali JavaScript/TypeScript SDK
+
+Official Node.js SDK for Centrali - Build modern web applications without managing infrastructure.
+
+[![npm version](https://badge.fury.io/js/%40centrali-io%2Fcentrali-sdk.svg)](https://www.npmjs.com/package/@centrali-io/centrali-sdk)
+
+## Installation
+
+```bash
+npm install @centrali-io/centrali-sdk
+```
+
+## Quick Start
+
+```typescript
+import { CentraliSDK } from '@centrali-io/centrali-sdk';
+
+// Initialize the SDK
+const centrali = new CentraliSDK({
+  baseUrl: 'https://centrali.io',
+  workspaceId: 'your-workspace',
+  token: 'your-api-key'
+});
+
+// Create a record
+const product = await centrali.createRecord('Product', {
+  name: 'Awesome Product',
+  price: 99.99,
+  inStock: true
+});
+
+console.log('Created product:', product.data);
+
+// Invoke a compute function
+const result = await centrali.invokeFunction('calculate-discount', {
+  productId: product.id,
+  couponCode: 'SAVE20'
+});
+
+console.log('Discount result:', result.data);
+```
+
+## Authentication
+
+The SDK supports two authentication methods:
+
+### Bearer Token (User Authentication)
+
+```typescript
+const centrali = new CentraliSDK({
+  baseUrl: 'https://centrali.io',
+  workspaceId: 'your-workspace',
+  token: 'your-jwt-token'
+});
+```
+
+### Service Account (Server-to-Server)
+
+```typescript
+const centrali = new CentraliSDK({
+  baseUrl: 'https://centrali.io',
+  workspaceId: 'your-workspace',
+  clientId: process.env.CENTRALI_CLIENT_ID,
+  clientSecret: process.env.CENTRALI_CLIENT_SECRET
+});
+
+// The SDK automatically fetches and manages tokens
+```
+
+## Features
+
+- ✅ **Type-safe API** with full TypeScript support
+- ✅ **Automatic authentication** and token management
+- ✅ **Records management** - Create, read, update, delete records
+- ✅ **Query operations** - Powerful data querying with filters and sorting
+- ✅ **Compute functions** - Execute serverless functions
+- ✅ **File uploads** - Upload files to Centrali storage
+- ✅ **Service accounts** - Automatic token refresh for server-to-server auth
+
+## Core Operations
+
+### Records
+
+```typescript
+// Create a record
+const record = await centrali.createRecord('StructureName', {
+  field1: 'value1',
+  field2: 123
+});
+
+// Get a record
+const record = await centrali.getRecord('StructureName', 'record-id');
+
+// Update a record
+await centrali.updateRecord('StructureName', 'record-id', {
+  field1: 'new value'
+});
+
+// Delete a record
+await centrali.deleteRecord('StructureName', 'record-id');
+
+// Query records
+const products = await centrali.queryRecords('Product', {
+  filter: 'inStock = true AND price < 100',
+  sort: '-createdAt',
+  limit: 10
+});
+```
+
+### Compute Functions
+
+```typescript
+// Execute a function
+const result = await centrali.invokeFunction('myFunction', {
+  data: 'your-input-data'
+});
+```
+
+### File Uploads
+
+```typescript
+// Upload a file
+const uploadResult = await centrali.uploadFile(
+  file,
+  'folder-name',
+  true  // make publicly accessible
+);
+
+console.log('File URL:', uploadResult.data);
+```
+
+## TypeScript Support
+
+The SDK includes full TypeScript definitions for type-safe development:
+
+```typescript
+interface Product {
+  name: string;
+  price: number;
+  inStock: boolean;
+}
+
+const product = await centrali.createRecord<Product>('Product', {
+  name: 'Laptop',
+  price: 999.99,
+  inStock: true
+});
+
+// TypeScript knows product.data is of type Product
+console.log(product.data.price);
+```
+
+## Error Handling
+
+```typescript
+try {
+  const record = await centrali.createRecord('Product', productData);
+  console.log('Success:', record);
+} catch (error) {
+  if (error.response?.status === 400) {
+    console.error('Validation error:', error.response.data);
+  } else if (error.response?.status === 401) {
+    console.error('Authentication failed');
+  } else {
+    console.error('Error:', error.message);
+  }
+}
+```
+
+## Documentation
+
+📚 **Full documentation available at**: [docs.centrali.io](https://docs.centrali.io)
+
+- [Complete SDK Guide](https://docs.centrali.io/guides/centrali-sdk)
+- [API Reference](https://docs.centrali.io/api-reference/overview)
+- [Quick Start Tutorial](https://docs.centrali.io/getting-started/02-quickstart)
+- [Compute Functions Guide](https://docs.centrali.io/guides/compute-functions-guide)
+
+## Examples
+
+Check out complete example applications:
+- [Blog Platform](https://docs.centrali.io/examples/blog-platform)
+- [E-commerce API](https://docs.centrali.io/examples/ecommerce-api)
+
+## Support
+
+- 📖 [Documentation](https://docs.centrali.io)
+- 🐛 [GitHub Issues](https://github.com/blueinit/centrali-sdk/issues)
+- 💬 [Community Support](https://centrali.io/community)
+
+## License
+
+ISC © Blueinit
+
+---
+
+**Built with ❤️ by the Centrali team**

package/dist/index.js

@@ -19,6 +19,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CentraliSDK = void 0;
+exports.getApiUrl = getApiUrl;
 exports.getAuthUrl = getAuthUrl;
 exports.fetchClientToken = fetchClientToken;
 exports.getRecordApiPath = getRecordApiPath;
@@ -31,25 +32,42 @@ function encodeFormData(data) {
     return new URLSearchParams(data).toString();
 }
 /**
- * Generate the auth server URL from the API base URL.
+ * Generate the API URL from the base URL by adding the 'api.' subdomain.
+ * E.g., https://centrali.io -> https://api.centrali.io
  */
-function getAuthUrl(apiBaseUrl) {
-    const url = new URL(apiBaseUrl);
-    // assume auth is hosted at auth.<api-domain>
-    return `${url.protocol}//auth.${url.hostname}`;
+function getApiUrl(baseUrl) {
+    const url = new URL(baseUrl);
+    // If already has 'api.' subdomain, return as-is
+    if (url.hostname.startsWith('api.')) {
+        return `${url.protocol}//${url.hostname}`;
+    }
+    return `${url.protocol}//api.${url.hostname}`;
+}
+/**
+ * Generate the auth server URL from the base URL.
+ * E.g., https://centrali.io -> https://auth.centrali.io
+ */
+function getAuthUrl(baseUrl) {
+    const url = new URL(baseUrl);
+    // Strip 'api.' prefix if present to get root domain
+    const hostname = url.hostname.startsWith('api.')
+        ? url.hostname.slice(4)
+        : url.hostname;
+    return `${url.protocol}//auth.${hostname}`;
 }
 /**
  * Retrieve an access token using the Client Credentials flow.
  */
-function fetchClientToken(clientId, clientSecret, apiBaseUrl) {
+function fetchClientToken(clientId, clientSecret, baseUrl) {
     return __awaiter(this, void 0, void 0, function* () {
-        const authUrl = getAuthUrl(apiBaseUrl);
+        const authUrl = getAuthUrl(baseUrl);
+        const apiUrl = getApiUrl(baseUrl);
         const tokenEndpoint = `${authUrl}/token`;
         const form = encodeFormData({
             grant_type: 'client_credentials',
             client_id: clientId,
             client_secret: clientSecret,
-            resource: `${apiBaseUrl}/data`
+            resource: `${apiUrl}/data`
         });
         const resp = yield axios_1.default.post(tokenEndpoint, form, { headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
             proxy: false
@@ -84,7 +102,8 @@ class CentraliSDK {
         this.token = null;
         this.options = options;
         this.token = options.token || null;
-        this.axios = axios_1.default.create(Object.assign({ baseURL: options.baseUrl, paramsSerializer: (params) => qs_1.default.stringify(params, { arrayFormat: "repeat" }), proxy: false }, options.axiosConfig));
+        const apiUrl = getApiUrl(options.baseUrl);
+        this.axios = axios_1.default.create(Object.assign({ baseURL: apiUrl, paramsSerializer: (params) => qs_1.default.stringify(params, { arrayFormat: "repeat" }), proxy: false }, options.axiosConfig));
         // Attach async interceptor to fetch token on first request if needed
         this.axios.interceptors.request.use((config) => __awaiter(this, void 0, void 0, function* () {
             if (!this.token && this.options.clientId && this.options.clientSecret) {
@@ -195,7 +214,7 @@ exports.CentraliSDK = CentraliSDK;
  * import { CentraliSDK, CentraliSDKOptions } from 'centrali-sdk';
  *
  * const options: CentraliSDKOptions = {
- *   baseUrl: 'https://api.centrali.com',
+ *   baseUrl: 'https://centrali.io',
  *   clientId: process.env.CLIENT_ID,
  *   clientSecret: process.env.CLIENT_SECRET,
  * };

package/index.ts

@@ -16,7 +16,7 @@ function encodeFormData(data: Record<string, string>): string {
  * Options for initializing the Centrali SDK client.
  */
 export interface CentraliSDKOptions {
-    /** Base URL of the Centrali API (e.g. https://api.centrali.com) */
+    /** Base URL of Centrali (e.g. https://centrali.io). The SDK automatically uses api.centrali.io for API calls. */
     baseUrl: string;
     workspaceId: string;
     /** Optional initial bearer token for authentication */
@@ -43,12 +43,29 @@ export interface ApiResponse<T> {
 
 
 /**
- * Generate the auth server URL from the API base URL.
+ * Generate the API URL from the base URL by adding the 'api.' subdomain.
+ * E.g., https://centrali.io -> https://api.centrali.io
  */
-export function getAuthUrl(apiBaseUrl: string): string {
-    const url = new URL(apiBaseUrl);
-    // assume auth is hosted at auth.<api-domain>
-    return `${url.protocol}//auth.${url.hostname}`;
+export function getApiUrl(baseUrl: string): string {
+    const url = new URL(baseUrl);
+    // If already has 'api.' subdomain, return as-is
+    if (url.hostname.startsWith('api.')) {
+        return `${url.protocol}//${url.hostname}`;
+    }
+    return `${url.protocol}//api.${url.hostname}`;
+}
+
+/**
+ * Generate the auth server URL from the base URL.
+ * E.g., https://centrali.io -> https://auth.centrali.io
+ */
+export function getAuthUrl(baseUrl: string): string {
+    const url = new URL(baseUrl);
+    // Strip 'api.' prefix if present to get root domain
+    const hostname = url.hostname.startsWith('api.')
+        ? url.hostname.slice(4)
+        : url.hostname;
+    return `${url.protocol}//auth.${hostname}`;
 }
 
 /**
@@ -57,15 +74,16 @@ export function getAuthUrl(apiBaseUrl: string): string {
 export async function fetchClientToken(
     clientId: string,
     clientSecret: string,
-    apiBaseUrl: string
+    baseUrl: string
 ): Promise<string> {
-    const authUrl = getAuthUrl(apiBaseUrl);
+    const authUrl = getAuthUrl(baseUrl);
+    const apiUrl = getApiUrl(baseUrl);
     const tokenEndpoint = `${authUrl}/token`;
     const form = encodeFormData({
         grant_type: 'client_credentials',
         client_id: clientId,
         client_secret: clientSecret,
-        resource: `${apiBaseUrl}/data`
+        resource: `${apiUrl}/data`
     });
     const resp = await axios.post(
         tokenEndpoint,
@@ -113,8 +131,9 @@ export class CentraliSDK {
     constructor(options: CentraliSDKOptions) {
         this.options = options;
         this.token = options.token || null;
+        const apiUrl = getApiUrl(options.baseUrl);
         this.axios = axios.create({
-            baseURL: options.baseUrl,
+            baseURL: apiUrl,
             paramsSerializer: (params: Record<string, any>): string =>
                     qs.stringify(params, { arrayFormat: "repeat" }),
             proxy: false,
@@ -299,7 +318,7 @@ export class CentraliSDK {
  * import { CentraliSDK, CentraliSDKOptions } from 'centrali-sdk';
  *
  * const options: CentraliSDKOptions = {
- *   baseUrl: 'https://api.centrali.com',
+ *   baseUrl: 'https://centrali.io',
  *   clientId: process.env.CLIENT_ID,
  *   clientSecret: process.env.CLIENT_SECRET,
  * };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-sdk",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Centrali Node SDK",
   "main": "dist/index.js",
   "type": "commonjs",