@mekari-officeless/sdk 0.1.0 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to `@mekari-officeless/sdk` are recorded here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
+project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Release process** — publishing is manual this phase. Merge to `main`, run
+> `npm version <patch|minor|major>`, push the commit and the tag, then
+> `npm publish --access public` from a clean checkout as an existing maintainer.
+> Move the entries below from _Unreleased_ into the new version heading in the same
+> pull request that bumps the version.
+
+## [Unreleased]
+
+### Added
+
+- `officeless.init({ sdkKey, gatewayUrl? })` — checks the key's shape and returns an
+  instance bound to it. Sends no request and returns no project data: the key's
+  company, project and stage stay server-side. Several instances can be held on one
+  page at once.
+- `app.auth.login(email)` — sends a login code and returns a `sessionId`.
+- `app.auth.verify(email, sessionId, code)` — confirms the code and starts the
+  session.
+- `app.auth.user()` — returns the signed-in person from the held session, without
+  sending a request.
+- `app.auth.refresh()` — renews the session.
+- `app.auth.logout()` — ends the session. Signing out twice does not throw.
+- `app.action.hitSDKFunction(name, data, withAuth?)` — runs a published automation
+  created with the **SDK Function** trigger and returns its output.
+- `OfficelessError`, carrying a `type` (`AuthorizationError`, `ValidationError`,
+  `WorkflowExecutionError`, `InternalServerError`) and the HTTP `status`, so a 429
+  can be told apart from a 401. A company without the feature turned on answers 404
+  like an unknown path, so there is deliberately no separate type for it.
+- The session survives a page reload: it is stored encrypted with AES-GCM, using a
+  non-extractable key held in IndexedDB.
+- TypeScript definitions for the whole surface, bundled to ESM and CommonJS with no
+  runtime dependencies.
+
+[Unreleased]: https://bitbucket.org/jojocoders/officeless-sdk/branches/compare/main

package/README.md

@@ -1,194 +1,324 @@
-# @officeless/sdk
+# 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.
+Run Officeless automations and sign users in, from your own web application.
 
-Zero dependencies. ESM-native. Works in any modern browser or Node.js 18+.
-
----
-
-## Installation
+- TypeScript, with full type definitions
+- ESM and CommonJS
+- No runtime dependencies
+- **Browser only** — see [Environment support](#environment-support)
 
 ```bash
-npm install @officeless/sdk
+npm install @mekari-officeless/sdk
 ```
 
 ---
 
-## Initialization
+## Getting started
+
+**1. Create an SDK key.** In Officeless Studio, open your project and go to
+**Settings › Developer access**, then create a key. Keys are fixed to one
+environment — `Development` or `Production` — when you create them, and that cannot
+be changed afterwards.
 
-There are two ways to initialize the client.
+**2. Add your domain.** On the same page, add the domain your application is served
+from to **Allowed domains**. Calls from any other domain are rejected. The list is
+shared by both environments of the project.
 
-### Mode A: URL Map (recommended after AI porting)
+**3. Set the library up.**
 
-When you have an `officeless.config.json` in your project root (auto-generated by the AI Porting Agent), import and pass it directly:
+```ts
+import { officeless } from '@mekari-officeless/sdk'
 
-```js
-import { OfficelessClient } from '@officeless/sdk'
-import config from './officeless.config.json' assert { type: 'json' }
+const app = await officeless.init({
+  sdkKey: 'ofc_sdk_prod_0123456789abcdef0123456789abcdef',
+})
 
-const client = OfficelessClient.fromConfig(config)
+// app → an instance: app.auth.login, app.auth.verify, app.action.hitSDKFunction, …
+// no project id, name, or stage — setup asks Officeless nothing
 ```
 
-The config file provides explicit webhook URLs for every workflow, so no guessing is needed.
+`init` sends no request. It checks the key's shape, keeps it with the gateway URL,
+and returns. So setup cannot fail on the network and adds nothing to your startup
+time — but it also cannot tell you the key is wrong. A wrong, revoked, or deleted
+key, a domain that is not on the allowed list, and a company without the feature
+turned on are all reported by your first real call: `login`, `verify`, `refresh`,
+`logout`, or `hitSDKFunction`.
 
-### Mode B: Base URL + convention
+Call it once, when your application starts. In a framework that server-renders —
+Next.js, Nuxt — call it from client-side code only (see
+[Environment support](#environment-support)).
 
-If you don't have a config file, initialize with just a base URL. Workflow names are mapped to `{baseUrl}/wh/{workflowName}` automatically.
+**4. Run an automation.**
 
-```js
-import { OfficelessClient } from '@officeless/sdk'
+```ts
+const result = await app.action.hitSDKFunction('calculate_payroll', { month: '2026-08' })
+// result → { status: 'success', output: { total: 8500000, period: '2026-08' } }
+```
 
-const client = new OfficelessClient({
-  baseUrl: 'https://api.officeless.io',
-  apiKey: 'olk_live_xxxx',      // optional
-  projectId: '2BfWnyXYk5mz',   // optional
-})
+---
+
+## Capabilities
+
+### `officeless.init({ sdkKey, gatewayUrl? })`
+
+Sets the library up and returns an instance bound to one key. Sends no request, and
+returns no project data — the key's company, project and stage stay server-side and
+are read from the key on every later call.
+
+The only failure it can raise is a value that is not shaped like an SDK key
+(`ofc_sdk_<stage>_<32 hex characters>`), thrown as a `ValidationError` with no HTTP
+status. A well-formed key that belongs to nothing passes here and fails on the first
+real call.
+
+Calling `init` again with a different key returns another, independent instance — one
+page can hold several at once, and they do not share a signed-in user.
+
+```ts
+const production = await officeless.init({ sdkKey: 'ofc_sdk_prod_…' })
+const staging = await officeless.init({ sdkKey: 'ofc_sdk_dev_…' })
 ```
 
-Constructor options:
+`gatewayUrl` is optional and defaults to `https://officeless-gateway.mekari.com/v1`.
+See [Single-tenant setup](#single-tenant-setup).
 
-| 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 }` |
+### `app.auth.login(email)`
 
----
+Sends a login code to the email and returns a `sessionId` for this attempt.
 
-## `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' },
-    },
-  },
-})
+```ts
+const { sessionId, otpExpiresAt } = await app.auth.login('user@example.com')
 ```
 
-Both snake_case (`base_url`, `api_key`, `project_id`) and camelCase (`baseUrl`, `apiKey`, `projectId`) keys are accepted.
+This resolves the same way whether or not the address belongs to a user of your
+project — and whether or not it is even a valid address. Nothing about the address
+changes the response, so this call cannot be used to discover who has an account.
+Do not treat a successful response as proof the address exists.
 
----
+### `app.auth.verify(email, sessionId, code)`
 
-## Triggering Workflows
+Confirms the code and starts the session.
 
-Use `client.workflow(name)` to get a `WorkflowRef`, then call `.trigger(payload)`.
+```ts
+const session = await app.auth.verify('user@example.com', sessionId, '482913')
+// session → { accessToken, refreshToken, expiredAt, user }
+```
 
-```js
-const result = await client.workflow('send-welcome-email').trigger({
-  userId: 42,
-  email: 'user@example.com',
-})
+The session is stored for you, so a page reload keeps the user signed in.
 
-console.log(result) // data returned by the workflow
+### `app.auth.user()`
+
+Returns the signed-in person. Reads the session your application already holds and
+sends no request.
+
+```ts
+const user = await app.auth.user()
+// user → { userId, email, name, companyId, companyName }
 ```
 
-The workflow name must match the key in `officeless.config.json` or the path segment in `{baseUrl}/wh/{name}`.
+Throws `AuthorizationError` when nobody is signed in or the session has expired.
 
----
+### `app.auth.refresh()`
 
-## Table CRUD
+Renews the session with the renewal token.
 
-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`.
+```ts
+const { accessToken, expiredAt } = await app.auth.refresh()
+```
 
-### `list(filters?)`
+There is no automatic refresh: the library does not retry a failed call by renewing
+in the background. Call `refresh()` yourself — for example when a call fails with
+`AuthorizationError` and `Session expired. Please log in again.`
 
-```js
-const employees = await client.table('employee').list({ department: 'engineering' })
-// calls workflow: employee-list  with payload: { filters: { department: 'engineering' } }
+### `app.auth.logout()`
+
+Ends the session, on the server and locally.
+
+```ts
+await app.auth.logout()
 ```
 
-### `create(data)`
+Calling it again on an already-ended session does not throw.
 
-```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' } }
+### `app.action.hitSDKFunction(name, data, withAuth?)`
+
+Runs a published automation by name and returns its output.
+
+```ts
+const result = await app.action.hitSDKFunction('calculate_payroll', { month: '2026-08' })
 ```
 
-### `update(id, data)`
+`name` is the **Function Name** set on the workflow's SDK Function trigger, not the
+workflow's display title. The automation must have been created with the **SDK
+Function** trigger — one built with any other trigger (Form event, API call, Webhook)
+is not reachable this way and reports as not found.
+
+`output` is whatever the automation returns: any JSON value, including `null`. It is
+passed through exactly as the automation produced it, so your own field names are
+never rewritten. Type it if you like:
 
-```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' } }
+```ts
+const result = await app.action.hitSDKFunction<{ total: number }>('calculate_payroll', {
+  month: '2026-08',
+})
+result.output.total // number
 ```
 
-### `delete(id)`
+`withAuth` defaults to `true` and only decides whether the SDK attaches the signed-in
+session to the call. Whether a session is actually _required_ is decided by the
+workflow's own **Required Authorization** setting, on the server. Passing
+`withAuth: false` to a workflow that requires one does not bypass it — the call is
+rejected.
 
-```js
-await client.table('employee').delete('emp_001')
-// calls workflow: employee-delete  with payload: { id: 'emp_001' }
+```ts
+// A workflow whose Required Authorization is off — no sign-in needed.
+await app.action.hitSDKFunction('submit_public_enquiry', data, false)
 ```
 
 ---
 
-## Error Handling
+## Errors
 
-All errors thrown by the SDK are instances of `OfficelessError`.
+Every failure is thrown as an `OfficelessError` carrying a `type` and the HTTP
+`status`. Branch on `type` — messages are written for people and may change.
 
-```js
-import { OfficelessClient, OfficelessError } from '@officeless/sdk'
+```ts
+import { OfficelessError } from '@mekari-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
+  await app.action.hitSDKFunction('calculate_payroll', { month: '2026-08' })
+} catch (error) {
+  if (error instanceof OfficelessError) {
+    switch (error.type) {
+      case 'AuthorizationError':
+        // Includes rate limiting — check error.status === 429 to tell it apart.
+        break
+      case 'ValidationError':
+        break
+      case 'WorkflowExecutionError':
+        break
+      case 'InternalServerError':
+        break
+    }
   }
 }
 ```
 
-`OfficelessError` extends the native `Error` class, so standard `instanceof` checks and stack traces work as expected.
+| `type`                   | What it means                                                                                                                       | What to do                                                                                                                                                      |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AuthorizationError`     | The key is wrong, revoked or deleted; the domain is not allowed; the session expired; or you are being rate limited (`status` 429). | Check `status`. On 401 with `Session expired`, call `refresh()` or sign the user in again. On 403 for the domain, add it in Studio. On 429, back off and retry. |
+| `ValidationError`        | An input did not match what the automation expects, or no function of that name exists in this project and stage.                   | Fix the input, or check the Function Name and that the workflow uses the SDK Function trigger and is published.                                                 |
+| `WorkflowExecutionError` | The automation itself failed partway, or ran past the time limit.                                                                   | Check the run in Studio's Run History. A run that fails halfway is not rolled back.                                                                             |
+| `InternalServerError`    | Something failed on Officeless's side, or the call never reached it.                                                                | Retry. If it persists, contact support.                                                                                                                         |
+
+`status` is `null` when the call never reached the server — offline, DNS failure, or
+a blocked CORS preflight.
 
 ---
 
-## `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" }
-    }
-  }
-}
+## Limits
+
+| Limit               | Value                                                                                                                                                                                  |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Function calls      | 100 requests per minute **per project** — shared across every key the project holds, Development and Production together. Exceeding it returns `AuthorizationError` with `status` 429. |
+| Setup calls         | Rate limited per key.                                                                                                                                                                  |
+| Session length      | 1 hour. Renew with `refresh()`.                                                                                                                                                        |
+| Renewal window      | 1 week.                                                                                                                                                                                |
+| Active sessions     | At most 3 per person. A fourth sign-in ends the oldest.                                                                                                                                |
+| Automation run time | 170 seconds. A longer run returns `WorkflowExecutionError`.                                                                                                                            |
+
+Revoking or deleting a key in Studio ends every session started with it, immediately.
+
+---
+
+## Single-tenant setup
+
+`gatewayUrl` points the SDK at a different Officeless deployment. It exists for
+single-tenant customers who run Officeless on their own domain. Most applications
+never set it.
+
+```ts
+const app = await officeless.init({
+  sdkKey: 'ofc_sdk_prod_…',
+  gatewayUrl: 'https://officeless.your-company.com/v1',
+})
 ```
 
-Fields:
+**What the SDK builds from it.** Every call is sent to
+`{gatewayUrl}/nocode/sdk/v1/…`. So `gatewayUrl` is the origin **plus whatever prefix
+your gateway is mounted under** — not the origin alone. The shared gateway mounts its
+services under `/v1` and strips that prefix before forwarding, which is why the
+default ends in it. Get this wrong and every call returns the gateway's own HTML 404
+rather than a JSON error, because the request never reaches Officeless at all.
+
+> **Set `gatewayUrl` once, in your own deployment configuration.**
+>
+> Never take it from a query parameter, a remotely-fetched config, or any other input
+> an attacker could influence. Your SDK key — and, once a user signs in, their live
+> session tokens — are sent to whatever host this resolves to. A `gatewayUrl` an
+> attacker controls is a `gatewayUrl` that receives those credentials.
+>
+> It cannot be restricted to a Mekari-owned allowlist, because for single-tenant
+> customers any domain may legitimately be correct. That makes it your build's
+> responsibility rather than something the library can enforce.
+
+---
+
+## Security notes
+
+**The SDK key is not a secret.** It ships inside your client-side code, and anyone
+can read it with browser developer tools. That is expected. Its protection is the
+allowed-domains list and the rate limit, not secrecy. If a key is misused, revoke it
+in Studio — that takes effect at once and ends every session started with it.
+
+**Stored sessions are encrypted, but that is not a defence against XSS.** The access
+and refresh tokens are kept in local storage, encrypted with AES-GCM using a
+non-extractable key held in IndexedDB, so the session survives a page reload. This
+raises the bar against a passive read — browser devtools on a shared machine, a copied
+browser profile. It does **not** protect against a script already running on your
+page: an XSS hole in your application can call the same decryption path the SDK does
+and read the tokens in the clear. Keeping the tokens in memory instead would be no
+better, since a script on the page can reach those too. Treat XSS in your own
+application as the control that matters here.
+
+---
+
+## Environment support
+
+This release is a **browser library**. It uses `fetch`, `localStorage`, `IndexedDB`
+and the Web Crypto API, and it relies on the browser setting the `Origin` header —
+that is what the allowed-domains check is based on.
+
+Running it on a server (Node, NestJS, Express, a Next.js route handler or server
+component) is **not supported in this release**. A server build needs a different
+security model, and is planned separately.
 
-| 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. |
+For frameworks that server-render, keep `init` and every call on the client side:
 
-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.
+```tsx
+'use client'
+
+import { useEffect, useState } from 'react'
+import { officeless, type OfficelessApp } from '@mekari-officeless/sdk'
+
+export function useOfficeless(sdkKey: string) {
+  const [app, setApp] = useState<OfficelessApp | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    officeless.init({ sdkKey }).then((instance) => {
+      if (!cancelled) setApp(instance)
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [sdkKey])
+
+  return app
+}
+```
 
 ---
 
 ## License
 
-MIT
+Proprietary — © Mekari. Distributed for use with Officeless.