@mekari-officeless/sdk 0.1.0

package/README.md

@@ -0,0 +1,194 @@
+# @officeless/sdk
+
+Official JavaScript SDK for frontend apps (React, Vue, vanilla JS) to interact with Officeless as a serverless backend via `api_v2` workflow triggers.
+
+Zero dependencies. ESM-native. Works in any modern browser or Node.js 18+.
+
+---
+
+## Installation
+
+```bash
+npm install @officeless/sdk
+```
+
+---
+
+## Initialization
+
+There are two ways to initialize the client.
+
+### Mode A: URL Map (recommended after AI porting)
+
+When you have an `officeless.config.json` in your project root (auto-generated by the AI Porting Agent), import and pass it directly:
+
+```js
+import { OfficelessClient } from '@officeless/sdk'
+import config from './officeless.config.json' assert { type: 'json' }
+
+const client = OfficelessClient.fromConfig(config)
+```
+
+The config file provides explicit webhook URLs for every workflow, so no guessing is needed.
+
+### Mode B: Base URL + convention
+
+If you don't have a config file, initialize with just a base URL. Workflow names are mapped to `{baseUrl}/wh/{workflowName}` automatically.
+
+```js
+import { OfficelessClient } from '@officeless/sdk'
+
+const client = new OfficelessClient({
+  baseUrl: 'https://api.officeless.io',
+  apiKey: 'olk_live_xxxx',      // optional
+  projectId: '2BfWnyXYk5mz',   // optional
+})
+```
+
+Constructor options:
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `baseUrl` | `string` | yes | Officeless API base URL |
+| `apiKey` | `string` | no | Sent as `X-Officeless-Key` header |
+| `projectId` | `string` | no | Your Officeless project ID |
+| `workflows` | `object` | no | Explicit map of workflow name → `{ url, method }` |
+
+---
+
+## `OfficelessClient.fromConfig(config)`
+
+Loads client settings from a plain object or a parsed `officeless.config.json`.
+
+```js
+const client = OfficelessClient.fromConfig({
+  officeless: {
+    project_id: '2BfWnyXYk5mz',
+    base_url: 'https://api.officeless.io',
+    api_key: 'olk_live_xxxx',
+    workflows: {
+      'employee-list':   { url: '/app/wh/abc123', method: 'post' },
+      'employee-create': { url: '/app/wh/def456', method: 'post' },
+    },
+  },
+})
+```
+
+Both snake_case (`base_url`, `api_key`, `project_id`) and camelCase (`baseUrl`, `apiKey`, `projectId`) keys are accepted.
+
+---
+
+## Triggering Workflows
+
+Use `client.workflow(name)` to get a `WorkflowRef`, then call `.trigger(payload)`.
+
+```js
+const result = await client.workflow('send-welcome-email').trigger({
+  userId: 42,
+  email: 'user@example.com',
+})
+
+console.log(result) // data returned by the workflow
+```
+
+The workflow name must match the key in `officeless.config.json` or the path segment in `{baseUrl}/wh/{name}`.
+
+---
+
+## Table CRUD
+
+Use `client.table(name)` to get a `TableRef` for a named table. Each method calls a corresponding workflow: `{tableName}-list`, `{tableName}-create`, `{tableName}-update`, `{tableName}-delete`.
+
+### `list(filters?)`
+
+```js
+const employees = await client.table('employee').list({ department: 'engineering' })
+// calls workflow: employee-list  with payload: { filters: { department: 'engineering' } }
+```
+
+### `create(data)`
+
+```js
+const newEmployee = await client.table('employee').create({
+  name: 'Jane Doe',
+  role: 'Engineer',
+})
+// calls workflow: employee-create  with payload: { data: { name: 'Jane Doe', role: 'Engineer' } }
+```
+
+### `update(id, data)`
+
+```js
+const updated = await client.table('employee').update('emp_001', { role: 'Senior Engineer' })
+// calls workflow: employee-update  with payload: { id: 'emp_001', data: { role: 'Senior Engineer' } }
+```
+
+### `delete(id)`
+
+```js
+await client.table('employee').delete('emp_001')
+// calls workflow: employee-delete  with payload: { id: 'emp_001' }
+```
+
+---
+
+## Error Handling
+
+All errors thrown by the SDK are instances of `OfficelessError`.
+
+```js
+import { OfficelessClient, OfficelessError } from '@officeless/sdk'
+
+try {
+  const data = await client.table('employee').list()
+} catch (err) {
+  if (err instanceof OfficelessError) {
+    console.error(err.message)      // human-readable message
+    console.error(err.statusCode)   // HTTP status code (e.g. 404, 500)
+    console.error(err.response)     // raw parsed response body, if available
+  } else {
+    throw err // re-throw unexpected errors
+  }
+}
+```
+
+`OfficelessError` extends the native `Error` class, so standard `instanceof` checks and stack traces work as expected.
+
+---
+
+## `officeless.config.json` Format
+
+This file is auto-generated by the AI Porting Agent and placed in the frontend project root. It maps each workflow to its webhook URL.
+
+```json
+{
+  "officeless": {
+    "project_id": "2BfWnyXYk5mz",
+    "base_url": "https://api.officeless.io",
+    "api_key": "olk_live_xxxx",
+    "workflows": {
+      "employee-list":   { "url": "/app/wh/abc123", "method": "post" },
+      "employee-create": { "url": "/app/wh/def456", "method": "post" },
+      "employee-update": { "url": "/app/wh/ghi789", "method": "post" },
+      "employee-delete": { "url": "/app/wh/jkl012", "method": "post" }
+    }
+  }
+}
+```
+
+Fields:
+
+| Field | Description |
+|-------|-------------|
+| `project_id` | Unique Officeless project identifier |
+| `base_url` | Base API URL for your Officeless instance |
+| `api_key` | Secret key for authenticating requests |
+| `workflows` | Map of workflow name → `{ url, method }`. `url` may be relative (resolved against `base_url`) or absolute. |
+
+Commit this file to your repository, but treat `api_key` as a secret — consider loading it from an environment variable in production and excluding the file from version control, or use a build-time substitution step.
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@mekari-officeless/sdk",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.1.0",
+  "description": "Official Officeless SDK for JS frontends",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "build": "echo 'build placeholder'"
+  },
+  "keywords": ["officeless", "sdk", "nocode"],
+  "license": "MIT"
+}

package/src/client.js

@@ -0,0 +1,84 @@
+import { WorkflowRef } from './workflow.js'
+import { TableRef } from './table.js'
+import { OfficelessError } from './errors.js'
+
+export class OfficelessClient {
+  /**
+   * @param {object} config
+   * @param {string} config.baseUrl - Officeless API base URL
+   * @param {string} [config.apiKey] - optional API key (sent as X-Officeless-Key header)
+   * @param {string} [config.projectId]
+   * @param {object} [config.workflows] - map of workflowName → { url, method }
+   *   e.g. { 'employee-list': { url: '/app/wh/abc123', method: 'post' } }
+   *   If provided, used directly. If not, uses baseUrl + /wh/ + name convention.
+   */
+  constructor(config = {}) {
+    if (!config.baseUrl) throw new OfficelessError('baseUrl is required')
+    this._baseUrl = config.baseUrl.replace(/\/$/, '')
+    this._apiKey = config.apiKey || null
+    this._projectId = config.projectId || null
+    this._workflowMap = config.workflows || {}
+  }
+
+  /**
+   * Load config from a plain object (e.g. imported officeless.config.json)
+   */
+  static fromConfig(config) {
+    const c = config?.officeless || config
+    return new OfficelessClient({
+      baseUrl: c.base_url || c.baseUrl,
+      apiKey: c.api_key || c.apiKey,
+      projectId: c.project_id || c.projectId,
+      workflows: c.workflows || {},
+    })
+  }
+
+  /** Returns a WorkflowRef for the named workflow */
+  workflow(name) {
+    return new WorkflowRef(this, name)
+  }
+
+  /** Returns a TableRef for the named table */
+  table(name) {
+    return new TableRef(this, name)
+  }
+
+  /** Internal: resolve workflow URL and POST to it */
+  async _callWorkflow(name, payload = {}) {
+    const entry = this._workflowMap[name]
+    let url
+    if (entry && entry.url) {
+      // URL map mode: url might be relative or absolute
+      url = entry.url.startsWith('http') ? entry.url : this._baseUrl + entry.url
+    } else {
+      // Convention mode: baseUrl/wh/workflow-name
+      url = `${this._baseUrl}/wh/${name}`
+    }
+
+    const headers = { 'Content-Type': 'application/json' }
+    if (this._apiKey) headers['X-Officeless-Key'] = this._apiKey
+
+    const res = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(payload),
+    })
+
+    let body
+    try {
+      body = await res.json()
+    } catch {
+      throw new OfficelessError(`Failed to parse response from ${name}`, res.status)
+    }
+
+    if (!res.ok || body?.error === true) {
+      throw new OfficelessError(
+        body?.message || `Request to ${name} failed`,
+        res.status,
+        body
+      )
+    }
+
+    return body?.data !== undefined ? body.data : body
+  }
+}

package/src/errors.js

@@ -0,0 +1,8 @@
+export class OfficelessError extends Error {
+  constructor(message, statusCode, response) {
+    super(message)
+    this.name = 'OfficelessError'
+    this.statusCode = statusCode
+    this.response = response
+  }
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { OfficelessClient } from './client.js'
+export { OfficelessError } from './errors.js'

package/src/table.js

@@ -0,0 +1,22 @@
+export class TableRef {
+  constructor(client, tableName) {
+    this._client = client
+    this._tableName = tableName
+  }
+
+  async list(filters = {}) {
+    return this._client._callWorkflow(`${this._tableName}-list`, { filters })
+  }
+
+  async create(data) {
+    return this._client._callWorkflow(`${this._tableName}-create`, { data })
+  }
+
+  async update(id, data) {
+    return this._client._callWorkflow(`${this._tableName}-update`, { id, data })
+  }
+
+  async delete(id) {
+    return this._client._callWorkflow(`${this._tableName}-delete`, { id })
+  }
+}

package/src/workflow.js

@@ -0,0 +1,10 @@
+export class WorkflowRef {
+  constructor(client, name) {
+    this._client = client
+    this._name = name
+  }
+
+  async trigger(payload = {}) {
+    return this._client._callWorkflow(this._name, payload)
+  }
+}