@lokal-server/ts-sdk 0.1.1

package/README.md

@@ -0,0 +1,129 @@
+# @lokal-server/ts-sdk
+
+TypeScript SDK for Lokal external apps. Lokal is a self-hosted file/data hub; this SDK helps apps define a manifest, authenticate a Lokal user, register the manifest, and read/write app-private JSON data.
+
+## Install
+
+```sh
+npm install @lokal-server/ts-sdk
+```
+
+## Define an app
+
+```ts
+import { createLokalClient, defineLokalApp } from '@lokal-server/ts-sdk';
+
+const recipeSchema = { type: 'object' };
+const settingsSchema = { type: 'object' };
+
+const manifest = defineLokalApp({
+  name: 'Recipe Box',
+  slug: 'recipe-box',
+  collections: {
+    recipes: recipeSchema,
+    settings: settingsSchema,
+  },
+});
+
+const lokal = createLokalClient({
+  instanceUrl: 'https://files.example.com',
+  manifest,
+});
+```
+
+`defineLokalApp()` preserves collection names as literal TypeScript keys, so `lokal.collection('recipes')` is accepted and unknown collection names are rejected by TypeScript.
+
+## Sign in
+
+```ts
+await lokal.auth.signIn({
+  email: 'user@example.com',
+  password: 'password',
+  tokenName: 'Recipe Box',
+});
+```
+
+Sign-in posts the manifest to `/api/platform/auth` and stores the returned app token in memory. You can also manage the token yourself:
+
+```ts
+lokal.setToken(savedToken);
+const token = lokal.getToken();
+lokal.clearToken();
+```
+
+The SDK does not persist tokens to `localStorage` or `sessionStorage`; consuming apps should choose their own persistence strategy.
+
+## Collection records
+
+```ts
+const recipes = lokal.collection('recipes');
+
+const created = await recipes.create({ title: 'Pancakes' }, { key: 'pancakes' });
+const all = await recipes.list({ limit: 20 });
+const one = await recipes.get(created.id);
+const updated = await recipes.update(created.id, { title: 'Blueberry Pancakes' });
+await recipes.delete(updated.id);
+```
+
+## Singleton values
+
+Use singleton values for one JSON document per collection, such as settings.
+
+```ts
+await lokal.collection('settings').setValue({ theme: 'dark' });
+const settings = await lokal.collection('settings').getValue();
+```
+
+## Custom fetch
+
+By default the SDK uses global `fetch`. Pass a custom implementation for tests or non-standard runtimes:
+
+```ts
+const lokal = createLokalClient({
+  instanceUrl: 'https://files.example.com',
+  manifest,
+  fetch: customFetch,
+});
+```
+
+## Errors
+
+Missing tokens throw a clear `Error`. Non-2xx API responses throw `LokalApiError` with `status`, `message`, and parsed `body` when available.
+
+```ts
+import { LokalApiError } from 'lokal-ts-sdk';
+
+try {
+  await lokal.collection('recipes').list();
+} catch (error) {
+  if (error instanceof LokalApiError) {
+    console.error(error.status, error.body);
+  }
+}
+```
+
+## Contracts
+
+The main Lokal repo owns the API contracts. Copies are kept in `contracts/`:
+
+- `contracts/openapi.json`
+- `contracts/lokal-manifest.schema.json`
+
+Update them with:
+
+```sh
+npm run contracts:update
+```
+
+If the OpenAPI contract changes, update SDK types, wrappers, and tests in the same change.
+
+## Publishing
+
+The package is configured for public npm publishing with `private: false`, `files: ["dist", "contracts", "README.md"]`, and `publishConfig.access: "public"`.
+
+Do not publish automatically. When ready, run checks and publish explicitly:
+
+```sh
+npm run check
+npm publish
+```

package/contracts/lokal-manifest.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lokal.local/contracts/lokal-manifest.schema.json",
+  "title": "Lokal app manifest",
+  "description": "Serializable shape sent by external apps from defineLokalApp during platform authentication.",
+  "type": "object",
+  "required": ["slug", "collections"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "description": {
+      "type": "string"
+    },
+    "developerName": {
+      "type": "string"
+    },
+    "collections": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9_-]+$"
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/contracts/openapi.json

@@ -0,0 +1,717 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Lokal Platform API",
+    "version": "0.1.0",
+    "description": "Contract for external apps integrating with Lokal as an app-private JSON data store."
+  },
+  "servers": [
+    {
+      "url": "{lokalUrl}",
+      "variables": {
+        "lokalUrl": {
+          "default": "https://files.example.com"
+        }
+      }
+    }
+  ],
+  "tags": [
+    {
+      "name": "Discovery"
+    },
+    {
+      "name": "Auth"
+    },
+    {
+      "name": "Records"
+    },
+    {
+      "name": "Values"
+    }
+  ],
+  "paths": {
+    "/.well-known/lokal": {
+      "get": {
+        "tags": ["Discovery"],
+        "operationId": "getLokalDiscovery",
+        "summary": "Discover Lokal platform capabilities",
+        "responses": {
+          "200": {
+            "description": "Lokal discovery metadata",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DiscoveryResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/platform/auth": {
+      "post": {
+        "tags": ["Auth"],
+        "operationId": "authenticateApp",
+        "summary": "Authenticate a Lokal user and register an app manifest",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AuthRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "User-bound app token and registered app metadata",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AuthResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    },
+    "/api/platform/apps/{appSlug}/collections/{collection}/records": {
+      "get": {
+        "tags": ["Records"],
+        "operationId": "listRecords",
+        "summary": "List records in an app-private collection for the authenticated user",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AppSlug"
+          },
+          {
+            "$ref": "#/components/parameters/Collection"
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100,
+              "default": 50
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Collection records",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/DataRecord"
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      },
+      "post": {
+        "tags": ["Records"],
+        "operationId": "createRecord",
+        "summary": "Create a record in an app-private collection for the authenticated user",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AppSlug"
+          },
+          {
+            "$ref": "#/components/parameters/Collection"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RecordWriteRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created record",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DataRecord"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    },
+    "/api/platform/apps/{appSlug}/collections/{collection}/records/{recordId}": {
+      "get": {
+        "tags": ["Records"],
+        "operationId": "getRecord",
+        "summary": "Read one collection record",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AppSlug"
+          },
+          {
+            "$ref": "#/components/parameters/Collection"
+          },
+          {
+            "$ref": "#/components/parameters/RecordId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Record",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DataRecord"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "patch": {
+        "tags": ["Records"],
+        "operationId": "updateRecord",
+        "summary": "Update one collection record",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AppSlug"
+          },
+          {
+            "$ref": "#/components/parameters/Collection"
+          },
+          {
+            "$ref": "#/components/parameters/RecordId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RecordWriteRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Updated record",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DataRecord"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "delete": {
+        "tags": ["Records"],
+        "operationId": "deleteRecord",
+        "summary": "Soft-delete one collection record",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AppSlug"
+          },
+          {
+            "$ref": "#/components/parameters/Collection"
+          },
+          {
+            "$ref": "#/components/parameters/RecordId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Delete result",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SuccessResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/api/platform/apps/{appSlug}/collections/{collection}/value": {
+      "get": {
+        "tags": ["Values"],
+        "operationId": "getCollectionValue",
+        "summary": "Read the singleton value for a collection",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AppSlug"
+          },
+          {
+            "$ref": "#/components/parameters/Collection"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Stored JSON value or null",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "oneOf": [
+                    {
+                      "$ref": "#/components/schemas/JsonValue"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      },
+      "put": {
+        "tags": ["Values"],
+        "operationId": "setCollectionValue",
+        "summary": "Set the singleton value for a collection",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AppSlug"
+          },
+          {
+            "$ref": "#/components/parameters/Collection"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ValueWriteRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Stored singleton record",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DataRecord"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "lokal_app token"
+      }
+    },
+    "parameters": {
+      "AppSlug": {
+        "name": "appSlug",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]+$"
+        }
+      },
+      "Collection": {
+        "name": "collection",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]+$"
+        }
+      },
+      "RecordId": {
+        "name": "recordId",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string"
+        }
+      }
+    },
+    "responses": {
+      "BadRequest": {
+        "description": "Invalid request",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            }
+          }
+        }
+      },
+      "Unauthorized": {
+        "description": "Missing or invalid credentials"
+      },
+      "NotFound": {
+        "description": "Resource not found"
+      }
+    },
+    "schemas": {
+      "JsonValue": {
+        "description": "Any JSON value. App-specific shape is validated by the external app or SDK.",
+        "nullable": true
+      },
+      "LokalAppManifest": {
+        "$ref": "./lokal-manifest.schema.json"
+      },
+      "AuthRequest": {
+        "type": "object",
+        "required": ["email", "password", "manifest"],
+        "properties": {
+          "email": {
+            "type": "string",
+            "format": "email"
+          },
+          "password": {
+            "type": "string"
+          },
+          "manifest": {
+            "$ref": "#/components/schemas/LokalAppManifest"
+          },
+          "lokalManifest": {
+            "$ref": "#/components/schemas/LokalAppManifest"
+          },
+          "app": {
+            "$ref": "#/components/schemas/LokalAppManifest"
+          },
+          "tokenName": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": true
+      },
+      "AuthResponse": {
+        "type": "object",
+        "required": ["apiBase", "app", "user", "token"],
+        "properties": {
+          "apiBase": {
+            "type": "string",
+            "format": "uri"
+          },
+          "app": {
+            "$ref": "#/components/schemas/RegisteredApp"
+          },
+          "user": {
+            "$ref": "#/components/schemas/LokalUser"
+          },
+          "token": {
+            "$ref": "#/components/schemas/AppTokenWithSecret"
+          }
+        }
+      },
+      "DiscoveryResponse": {
+        "type": "object",
+        "required": ["issuer", "apiBase", "features"],
+        "properties": {
+          "issuer": {
+            "type": "string",
+            "format": "uri"
+          },
+          "apiBase": {
+            "type": "string",
+            "format": "uri"
+          },
+          "contracts": {
+            "type": "object",
+            "properties": {
+              "openapi": {
+                "type": "string"
+              },
+              "manifestSchema": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          },
+          "features": {
+            "type": "object",
+            "properties": {
+              "auth": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "data": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "files": {
+                "type": "boolean"
+              }
+            },
+            "additionalProperties": true
+          }
+        },
+        "additionalProperties": false
+      },
+      "RegisteredApp": {
+        "type": "object",
+        "required": ["id", "name", "slug", "clientId", "manifest"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "slug": {
+            "type": "string"
+          },
+          "clientId": {
+            "type": "string"
+          },
+          "manifest": {
+            "$ref": "#/components/schemas/LokalAppManifest"
+          }
+        },
+        "additionalProperties": true
+      },
+      "LokalUser": {
+        "type": "object",
+        "required": ["id", "name", "email", "role"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "email": {
+            "type": "string",
+            "format": "email"
+          },
+          "role": {
+            "type": "string"
+          }
+        }
+      },
+      "AppTokenWithSecret": {
+        "type": "object",
+        "required": ["id", "name", "scopes", "createdAt", "type", "rawToken"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "scopes": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["data:read", "data:write"]
+            }
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "type": {
+            "type": "string",
+            "const": "Bearer"
+          },
+          "rawToken": {
+            "type": "string",
+            "pattern": "^lokal_app_"
+          }
+        }
+      },
+      "DataRecord": {
+        "type": "object",
+        "required": ["id", "appId", "ownerId", "collection", "value", "version", "createdAt", "updatedAt"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "appId": {
+            "type": "string"
+          },
+          "ownerId": {
+            "type": "string"
+          },
+          "collection": {
+            "type": "string"
+          },
+          "key": {
+            "type": ["string", "null"]
+          },
+          "value": {
+            "$ref": "#/components/schemas/JsonValue"
+          },
+          "version": {
+            "type": "integer"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "deletedAt": {
+            "type": ["string", "null"],
+            "format": "date-time"
+          }
+        },
+        "additionalProperties": true
+      },
+      "RecordWriteRequest": {
+        "description": "Either send { value, key? } or send any JSON value directly. The SDK should prefer { value }.",
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "key": {
+                "type": ["string", "null"]
+              },
+              "value": {
+                "$ref": "#/components/schemas/JsonValue"
+              }
+            },
+            "required": ["value"],
+            "additionalProperties": true
+          },
+          {
+            "$ref": "#/components/schemas/JsonValue"
+          }
+        ]
+      },
+      "ValueWriteRequest": {
+        "description": "Either send { value } or send any JSON value directly. The SDK should prefer { value }.",
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "value": {
+                "$ref": "#/components/schemas/JsonValue"
+              }
+            },
+            "required": ["value"],
+            "additionalProperties": true
+          },
+          {
+            "$ref": "#/components/schemas/JsonValue"
+          }
+        ]
+      },
+      "SuccessResponse": {
+        "type": "object",
+        "required": ["success"],
+        "properties": {
+          "success": {
+            "type": "boolean"
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "required": ["error"],
+        "properties": {
+          "error": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/dist/client.d.ts

@@ -0,0 +1,3 @@
+import type { CreateLokalClientOptions, LokalAppManifest, LokalClient } from './types';
+export declare function createLokalClient<Manifest extends LokalAppManifest>(options: CreateLokalClientOptions<Manifest>): LokalClient<Manifest>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,wBAAwB,EAGxB,gBAAgB,EAChB,WAAW,EAGZ,MAAM,SAAS,CAAC;AAMjB,wBAAgB,iBAAiB,CAAC,QAAQ,SAAS,gBAAgB,EACjE,OAAO,EAAE,wBAAwB,CAAC,QAAQ,CAAC,GAC1C,WAAW,CAAC,QAAQ,CAAC,CA4HvB"}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class LokalApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAM5D"}

package/dist/index.cjs

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=class extends Error{status;body;constructor(e,t,n){super(t),this.name=`LokalApiError`,this.status=e,this.body=n}};function t(t){let a=n(t.instanceUrl),o=t.fetch??globalThis.fetch,s=t.token;if(!o)throw Error(`A fetch implementation is required. Pass fetch in createLokalClient options.`);async function c(t,n={}){let{requiresToken:c=!0,headers:l,...u}=n,d=new Headers(l);if(d.set(`Accept`,`application/json`),u.body!==void 0&&!d.has(`Content-Type`)&&d.set(`Content-Type`,`application/json`),c){if(!s)throw Error(`A Lokal app token is required. Sign in first or call setToken().`);d.set(`Authorization`,`Bearer ${s}`)}let f=await o(`${a}${t}`,{...u,headers:d}),p=await r(f);if(!f.ok)throw new e(f.status,i(f,p),p);return p}let l={async signIn(e){let n=await c(`/api/platform/auth`,{method:`POST`,requiresToken:!1,body:JSON.stringify({email:e.email,password:e.password,manifest:t.manifest,...e.tokenName?{tokenName:e.tokenName}:{}})});return s=n.token.rawToken,n}};function u(e){let n=`/api/platform/apps/${encodeURIComponent(t.manifest.slug)}/collections/${encodeURIComponent(e)}`;return{list(e){let t=new URLSearchParams;e?.limit!==void 0&&t.set(`limit`,String(e.limit));let r=t.toString();return c(`${n}/records${r?`?${r}`:``}`)},create(e,t){return c(`${n}/records`,{method:`POST`,body:JSON.stringify({value:e,...t?.key===void 0?{}:{key:t.key}})})},get(e){return c(`${n}/records/${encodeURIComponent(e)}`)},update(e,t,r){return c(`${n}/records/${encodeURIComponent(e)}`,{method:`PATCH`,body:JSON.stringify({value:t,...r&&`key`in r?{key:r.key}:{}})})},delete(e){return c(`${n}/records/${encodeURIComponent(e)}`,{method:`DELETE`})},getValue(){return c(`${n}/value`)},setValue(e){return c(`${n}/value`,{method:`PUT`,body:JSON.stringify({value:e})})}}}return{auth:l,setToken(e){s=e},getToken(){return s},clearToken(){s=void 0},collection:u}}function n(e){let t=e.trim().replace(/\/+$/,``);if(!t)throw Error(`instanceUrl is required.`);return t}async function r(e){let t=await e.text();if(t)try{return JSON.parse(t)}catch{return t}}function i(e,t){if(t&&typeof t==`object`){if(`error`in t&&typeof t.error==`string`)return t.error;if(`message`in t&&typeof t.message==`string`)return t.message}return`Lokal API request failed with status ${e.status}`}function a(e){return e}exports.LokalApiError=e,exports.createLokalClient=t,exports.defineLokalApp=a;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/errors.ts","../src/client.ts","../src/manifest.ts"],"sourcesContent":["export class LokalApiError extends Error {\n  readonly status: number;\n  readonly body: unknown;\n\n  constructor(status: number, message: string, body?: unknown) {\n    super(message);\n    this.name = 'LokalApiError';\n    this.status = status;\n    this.body = body;\n  }\n}\n","import { LokalApiError } from './errors';\nimport type {\n  AuthResponse,\n  AuthSignInOptions,\n  CreateLokalClientOptions,\n  DataRecord,\n  JsonValue,\n  LokalAppManifest,\n  LokalClient,\n  LokalCollectionClient,\n  SuccessResponse,\n} from './types';\n\ninterface RequestOptions extends RequestInit {\n  requiresToken?: boolean;\n}\n\nexport function createLokalClient<Manifest extends LokalAppManifest>(\n  options: CreateLokalClientOptions<Manifest>,\n): LokalClient<Manifest> {\n  const instanceUrl = normalizeInstanceUrl(options.instanceUrl);\n  const fetcher = options.fetch ?? globalThis.fetch;\n  let token = options.token;\n\n  if (!fetcher) {\n    throw new Error('A fetch implementation is required. Pass fetch in createLokalClient options.');\n  }\n\n  async function request<Result>(path: string, requestOptions: RequestOptions = {}): Promise<Result> {\n    const { requiresToken = true, headers, ...init } = requestOptions;\n    const requestHeaders = new Headers(headers);\n\n    requestHeaders.set('Accept', 'application/json');\n\n    if (init.body !== undefined && !requestHeaders.has('Content-Type')) {\n      requestHeaders.set('Content-Type', 'application/json');\n    }\n\n    if (requiresToken) {\n      if (!token) {\n        throw new Error('A Lokal app token is required. Sign in first or call setToken().');\n      }\n      requestHeaders.set('Authorization', `Bearer ${token}`);\n    }\n\n    const response = await fetcher(`${instanceUrl}${path}`, {\n      ...init,\n      headers: requestHeaders,\n    });\n\n    const body = await readBody(response);\n\n    if (!response.ok) {\n      throw new LokalApiError(response.status, getErrorMessage(response, body), body);\n    }\n\n    return body as Result;\n  }\n\n  const auth = {\n    async signIn(signInOptions: AuthSignInOptions): Promise<AuthResponse<Manifest>> {\n      const response = await request<AuthResponse<Manifest>>('/api/platform/auth', {\n        method: 'POST',\n        requiresToken: false,\n        body: JSON.stringify({\n          email: signInOptions.email,\n          password: signInOptions.password,\n          manifest: options.manifest,\n          ...(signInOptions.tokenName ? { tokenName: signInOptions.tokenName } : {}),\n        }),\n      });\n\n      token = response.token.rawToken;\n      return response;\n    },\n  };\n\n  function collection(name: string): LokalCollectionClient {\n    const collectionPath = `/api/platform/apps/${encodeURIComponent(\n      options.manifest.slug,\n    )}/collections/${encodeURIComponent(name)}`;\n\n    return {\n      list(listOptions) {\n        const search = new URLSearchParams();\n        if (listOptions?.limit !== undefined) {\n          search.set('limit', String(listOptions.limit));\n        }\n\n        const query = search.toString();\n        return request<DataRecord[]>(`${collectionPath}/records${query ? `?${query}` : ''}`);\n      },\n      create(value: JsonValue, writeOptions) {\n        return request<DataRecord>(`${collectionPath}/records`, {\n          method: 'POST',\n          body: JSON.stringify({\n            value,\n            ...(writeOptions?.key !== undefined ? { key: writeOptions.key } : {}),\n          }),\n        });\n      },\n      get(recordId: string) {\n        return request<DataRecord>(`${collectionPath}/records/${encodeURIComponent(recordId)}`);\n      },\n      update(recordId: string, value: JsonValue, updateOptions) {\n        return request<DataRecord>(`${collectionPath}/records/${encodeURIComponent(recordId)}`, {\n          method: 'PATCH',\n          body: JSON.stringify({\n            value,\n            ...(updateOptions && 'key' in updateOptions ? { key: updateOptions.key } : {}),\n          }),\n        });\n      },\n      delete(recordId: string) {\n        return request<SuccessResponse>(`${collectionPath}/records/${encodeURIComponent(recordId)}`, {\n          method: 'DELETE',\n        });\n      },\n      getValue() {\n        return request<JsonValue | null>(`${collectionPath}/value`);\n      },\n      setValue(value: JsonValue) {\n        return request<DataRecord>(`${collectionPath}/value`, {\n          method: 'PUT',\n          body: JSON.stringify({ value }),\n        });\n      },\n    };\n  }\n\n  return {\n    auth,\n    setToken(nextToken: string) {\n      token = nextToken;\n    },\n    getToken() {\n      return token;\n    },\n    clearToken() {\n      token = undefined;\n    },\n    collection,\n  } as LokalClient<Manifest>;\n}\n\nfunction normalizeInstanceUrl(instanceUrl: string): string {\n  const normalized = instanceUrl.trim().replace(/\\/+$/, '');\n  if (!normalized) {\n    throw new Error('instanceUrl is required.');\n  }\n  return normalized;\n}\n\nasync function readBody(response: Response): Promise<unknown> {\n  const text = await response.text();\n  if (!text) {\n    return undefined;\n  }\n\n  try {\n    return JSON.parse(text);\n  } catch {\n    return text;\n  }\n}\n\nfunction getErrorMessage(response: Response, body: unknown): string {\n  if (body && typeof body === 'object') {\n    if ('error' in body && typeof body.error === 'string') {\n      return body.error;\n    }\n    if ('message' in body && typeof body.message === 'string') {\n      return body.message;\n    }\n  }\n\n  return `Lokal API request failed with status ${response.status}`;\n}\n","import type { LokalAppManifest, LokalCollections } from './types';\n\nexport function defineLokalApp<const Collections extends LokalCollections>(\n  manifest: LokalAppManifest<Collections>,\n): LokalAppManifest<Collections> {\n  return manifest;\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createLokalClient } from './client';
+export { LokalApiError } from './errors';
+export { defineLokalApp } from './manifest';
+export type { AppTokenWithSecret, AuthResponse, AuthSignInOptions, CreateLokalClientOptions, DataRecord, JsonValue, LokalAppManifest, LokalClient, LokalCollectionClient, LokalCollections, LokalUser, RegisteredApp, SuccessResponse, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EACV,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,wBAAwB,EACxB,UAAU,EACV,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,qBAAqB,EACrB,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,eAAe,GAChB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,126 @@
+//#region src/errors.ts
+var e = class extends Error {
+	status;
+	body;
+	constructor(e, t, n) {
+		super(t), this.name = "LokalApiError", this.status = e, this.body = n;
+	}
+};
+//#endregion
+//#region src/client.ts
+function t(t) {
+	let a = n(t.instanceUrl), o = t.fetch ?? globalThis.fetch, s = t.token;
+	if (!o) throw Error("A fetch implementation is required. Pass fetch in createLokalClient options.");
+	async function c(t, n = {}) {
+		let { requiresToken: c = !0, headers: l, ...u } = n, d = new Headers(l);
+		if (d.set("Accept", "application/json"), u.body !== void 0 && !d.has("Content-Type") && d.set("Content-Type", "application/json"), c) {
+			if (!s) throw Error("A Lokal app token is required. Sign in first or call setToken().");
+			d.set("Authorization", `Bearer ${s}`);
+		}
+		let f = await o(`${a}${t}`, {
+			...u,
+			headers: d
+		}), p = await r(f);
+		if (!f.ok) throw new e(f.status, i(f, p), p);
+		return p;
+	}
+	let l = { async signIn(e) {
+		let n = await c("/api/platform/auth", {
+			method: "POST",
+			requiresToken: !1,
+			body: JSON.stringify({
+				email: e.email,
+				password: e.password,
+				manifest: t.manifest,
+				...e.tokenName ? { tokenName: e.tokenName } : {}
+			})
+		});
+		return s = n.token.rawToken, n;
+	} };
+	function u(e) {
+		let n = `/api/platform/apps/${encodeURIComponent(t.manifest.slug)}/collections/${encodeURIComponent(e)}`;
+		return {
+			list(e) {
+				let t = new URLSearchParams();
+				e?.limit !== void 0 && t.set("limit", String(e.limit));
+				let r = t.toString();
+				return c(`${n}/records${r ? `?${r}` : ""}`);
+			},
+			create(e, t) {
+				return c(`${n}/records`, {
+					method: "POST",
+					body: JSON.stringify({
+						value: e,
+						...t?.key === void 0 ? {} : { key: t.key }
+					})
+				});
+			},
+			get(e) {
+				return c(`${n}/records/${encodeURIComponent(e)}`);
+			},
+			update(e, t, r) {
+				return c(`${n}/records/${encodeURIComponent(e)}`, {
+					method: "PATCH",
+					body: JSON.stringify({
+						value: t,
+						...r && "key" in r ? { key: r.key } : {}
+					})
+				});
+			},
+			delete(e) {
+				return c(`${n}/records/${encodeURIComponent(e)}`, { method: "DELETE" });
+			},
+			getValue() {
+				return c(`${n}/value`);
+			},
+			setValue(e) {
+				return c(`${n}/value`, {
+					method: "PUT",
+					body: JSON.stringify({ value: e })
+				});
+			}
+		};
+	}
+	return {
+		auth: l,
+		setToken(e) {
+			s = e;
+		},
+		getToken() {
+			return s;
+		},
+		clearToken() {
+			s = void 0;
+		},
+		collection: u
+	};
+}
+function n(e) {
+	let t = e.trim().replace(/\/+$/, "");
+	if (!t) throw Error("instanceUrl is required.");
+	return t;
+}
+async function r(e) {
+	let t = await e.text();
+	if (t) try {
+		return JSON.parse(t);
+	} catch {
+		return t;
+	}
+}
+function i(e, t) {
+	if (t && typeof t == "object") {
+		if ("error" in t && typeof t.error == "string") return t.error;
+		if ("message" in t && typeof t.message == "string") return t.message;
+	}
+	return `Lokal API request failed with status ${e.status}`;
+}
+//#endregion
+//#region src/manifest.ts
+function a(e) {
+	return e;
+}
+//#endregion
+export { e as LokalApiError, t as createLokalClient, a as defineLokalApp };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/errors.ts","../src/client.ts","../src/manifest.ts"],"sourcesContent":["export class LokalApiError extends Error {\n  readonly status: number;\n  readonly body: unknown;\n\n  constructor(status: number, message: string, body?: unknown) {\n    super(message);\n    this.name = 'LokalApiError';\n    this.status = status;\n    this.body = body;\n  }\n}\n","import { LokalApiError } from './errors';\nimport type {\n  AuthResponse,\n  AuthSignInOptions,\n  CreateLokalClientOptions,\n  DataRecord,\n  JsonValue,\n  LokalAppManifest,\n  LokalClient,\n  LokalCollectionClient,\n  SuccessResponse,\n} from './types';\n\ninterface RequestOptions extends RequestInit {\n  requiresToken?: boolean;\n}\n\nexport function createLokalClient<Manifest extends LokalAppManifest>(\n  options: CreateLokalClientOptions<Manifest>,\n): LokalClient<Manifest> {\n  const instanceUrl = normalizeInstanceUrl(options.instanceUrl);\n  const fetcher = options.fetch ?? globalThis.fetch;\n  let token = options.token;\n\n  if (!fetcher) {\n    throw new Error('A fetch implementation is required. Pass fetch in createLokalClient options.');\n  }\n\n  async function request<Result>(path: string, requestOptions: RequestOptions = {}): Promise<Result> {\n    const { requiresToken = true, headers, ...init } = requestOptions;\n    const requestHeaders = new Headers(headers);\n\n    requestHeaders.set('Accept', 'application/json');\n\n    if (init.body !== undefined && !requestHeaders.has('Content-Type')) {\n      requestHeaders.set('Content-Type', 'application/json');\n    }\n\n    if (requiresToken) {\n      if (!token) {\n        throw new Error('A Lokal app token is required. Sign in first or call setToken().');\n      }\n      requestHeaders.set('Authorization', `Bearer ${token}`);\n    }\n\n    const response = await fetcher(`${instanceUrl}${path}`, {\n      ...init,\n      headers: requestHeaders,\n    });\n\n    const body = await readBody(response);\n\n    if (!response.ok) {\n      throw new LokalApiError(response.status, getErrorMessage(response, body), body);\n    }\n\n    return body as Result;\n  }\n\n  const auth = {\n    async signIn(signInOptions: AuthSignInOptions): Promise<AuthResponse<Manifest>> {\n      const response = await request<AuthResponse<Manifest>>('/api/platform/auth', {\n        method: 'POST',\n        requiresToken: false,\n        body: JSON.stringify({\n          email: signInOptions.email,\n          password: signInOptions.password,\n          manifest: options.manifest,\n          ...(signInOptions.tokenName ? { tokenName: signInOptions.tokenName } : {}),\n        }),\n      });\n\n      token = response.token.rawToken;\n      return response;\n    },\n  };\n\n  function collection(name: string): LokalCollectionClient {\n    const collectionPath = `/api/platform/apps/${encodeURIComponent(\n      options.manifest.slug,\n    )}/collections/${encodeURIComponent(name)}`;\n\n    return {\n      list(listOptions) {\n        const search = new URLSearchParams();\n        if (listOptions?.limit !== undefined) {\n          search.set('limit', String(listOptions.limit));\n        }\n\n        const query = search.toString();\n        return request<DataRecord[]>(`${collectionPath}/records${query ? `?${query}` : ''}`);\n      },\n      create(value: JsonValue, writeOptions) {\n        return request<DataRecord>(`${collectionPath}/records`, {\n          method: 'POST',\n          body: JSON.stringify({\n            value,\n            ...(writeOptions?.key !== undefined ? { key: writeOptions.key } : {}),\n          }),\n        });\n      },\n      get(recordId: string) {\n        return request<DataRecord>(`${collectionPath}/records/${encodeURIComponent(recordId)}`);\n      },\n      update(recordId: string, value: JsonValue, updateOptions) {\n        return request<DataRecord>(`${collectionPath}/records/${encodeURIComponent(recordId)}`, {\n          method: 'PATCH',\n          body: JSON.stringify({\n            value,\n            ...(updateOptions && 'key' in updateOptions ? { key: updateOptions.key } : {}),\n          }),\n        });\n      },\n      delete(recordId: string) {\n        return request<SuccessResponse>(`${collectionPath}/records/${encodeURIComponent(recordId)}`, {\n          method: 'DELETE',\n        });\n      },\n      getValue() {\n        return request<JsonValue | null>(`${collectionPath}/value`);\n      },\n      setValue(value: JsonValue) {\n        return request<DataRecord>(`${collectionPath}/value`, {\n          method: 'PUT',\n          body: JSON.stringify({ value }),\n        });\n      },\n    };\n  }\n\n  return {\n    auth,\n    setToken(nextToken: string) {\n      token = nextToken;\n    },\n    getToken() {\n      return token;\n    },\n    clearToken() {\n      token = undefined;\n    },\n    collection,\n  } as LokalClient<Manifest>;\n}\n\nfunction normalizeInstanceUrl(instanceUrl: string): string {\n  const normalized = instanceUrl.trim().replace(/\\/+$/, '');\n  if (!normalized) {\n    throw new Error('instanceUrl is required.');\n  }\n  return normalized;\n}\n\nasync function readBody(response: Response): Promise<unknown> {\n  const text = await response.text();\n  if (!text) {\n    return undefined;\n  }\n\n  try {\n    return JSON.parse(text);\n  } catch {\n    return text;\n  }\n}\n\nfunction getErrorMessage(response: Response, body: unknown): string {\n  if (body && typeof body === 'object') {\n    if ('error' in body && typeof body.error === 'string') {\n      return body.error;\n    }\n    if ('message' in body && typeof body.message === 'string') {\n      return body.message;\n    }\n  }\n\n  return `Lokal API request failed with status ${response.status}`;\n}\n","import type { LokalAppManifest, LokalCollections } from './types';\n\nexport function defineLokalApp<const Collections extends LokalCollections>(\n  manifest: LokalAppManifest<Collections>,\n): LokalAppManifest<Collections> {\n  return manifest;\n}\n"],"mappings":"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"}

package/dist/manifest.d.ts

@@ -0,0 +1,3 @@
+import type { LokalAppManifest, LokalCollections } from './types';
+export declare function defineLokalApp<const Collections extends LokalCollections>(manifest: LokalAppManifest<Collections>): LokalAppManifest<Collections>;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAElE,wBAAgB,cAAc,CAAC,KAAK,CAAC,WAAW,SAAS,gBAAgB,EACvE,QAAQ,EAAE,gBAAgB,CAAC,WAAW,CAAC,GACtC,gBAAgB,CAAC,WAAW,CAAC,CAE/B"}

package/dist/types.d.ts

@@ -0,0 +1,96 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type LokalCollections = Record<string, unknown>;
+export interface LokalAppManifest<Collections extends LokalCollections = LokalCollections> {
+    name?: string;
+    slug: string;
+    description?: string;
+    developerName?: string;
+    collections: Collections;
+}
+export interface LokalUser {
+    id: string;
+    name: string;
+    email: string;
+    role: string;
+}
+export interface RegisteredApp<Manifest extends LokalAppManifest = LokalAppManifest> {
+    id: string;
+    name: string;
+    slug: string;
+    clientId: string;
+    manifest: Manifest;
+    [key: string]: unknown;
+}
+export interface AppTokenWithSecret {
+    id: string;
+    name: string;
+    scopes: Array<'data:read' | 'data:write'>;
+    createdAt: string;
+    type: 'Bearer';
+    rawToken: string;
+}
+export interface AuthResponse<Manifest extends LokalAppManifest = LokalAppManifest> {
+    apiBase: string;
+    app: RegisteredApp<Manifest>;
+    user: LokalUser;
+    token: AppTokenWithSecret;
+}
+export interface AuthSignInOptions {
+    email: string;
+    password: string;
+    tokenName?: string;
+}
+export interface DataRecord<Value extends JsonValue = JsonValue> {
+    id: string;
+    appId: string;
+    ownerId: string;
+    collection: string;
+    value: Value;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt?: string | null;
+    key?: string | null;
+    [key: string]: unknown;
+}
+export interface SuccessResponse {
+    success: boolean;
+}
+export interface ListOptions {
+    limit?: number;
+}
+export interface WriteOptions {
+    key?: string;
+}
+export interface UpdateOptions {
+    key?: string | null;
+}
+export interface LokalCollectionClient {
+    list(options?: ListOptions): Promise<DataRecord[]>;
+    create(value: JsonValue, options?: WriteOptions): Promise<DataRecord>;
+    get(recordId: string): Promise<DataRecord>;
+    update(recordId: string, value: JsonValue, options?: UpdateOptions): Promise<DataRecord>;
+    delete(recordId: string): Promise<SuccessResponse>;
+    getValue(): Promise<JsonValue | null>;
+    setValue(value: JsonValue): Promise<DataRecord>;
+}
+export type CollectionName<Manifest extends LokalAppManifest> = Extract<keyof Manifest['collections'], string>;
+export interface LokalClient<Manifest extends LokalAppManifest = LokalAppManifest> {
+    auth: {
+        signIn(options: AuthSignInOptions): Promise<AuthResponse<Manifest>>;
+    };
+    setToken(token: string): void;
+    getToken(): string | undefined;
+    clearToken(): void;
+    collection(name: CollectionName<Manifest>): LokalCollectionClient;
+}
+export interface CreateLokalClientOptions<Manifest extends LokalAppManifest = LokalAppManifest> {
+    instanceUrl: string;
+    manifest: Manifest;
+    token?: string;
+    fetch?: typeof fetch;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAC7D,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEnF,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvD,MAAM,WAAW,gBAAgB,CAAC,WAAW,SAAS,gBAAgB,GAAG,gBAAgB;IACvF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa,CAAC,QAAQ,SAAS,gBAAgB,GAAG,gBAAgB;IACjF,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,CAAC,WAAW,GAAG,YAAY,CAAC,CAAC;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY,CAAC,QAAQ,SAAS,gBAAgB,GAAG,gBAAgB;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,kBAAkB,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACnD,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtE,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3C,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACzF,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACnD,QAAQ,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACjD;AAED,MAAM,MAAM,cAAc,CAAC,QAAQ,SAAS,gBAAgB,IAAI,OAAO,CACrE,MAAM,QAAQ,CAAC,aAAa,CAAC,EAC7B,MAAM,CACP,CAAC;AAEF,MAAM,WAAW,WAAW,CAAC,QAAQ,SAAS,gBAAgB,GAAG,gBAAgB;IAC/E,IAAI,EAAE;QACJ,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC;KACrE,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,IAAI,MAAM,GAAG,SAAS,CAAC;IAC/B,UAAU,IAAI,IAAI,CAAC;IACnB,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,qBAAqB,CAAC;CACnE;AAED,MAAM,WAAW,wBAAwB,CAAC,QAAQ,SAAS,gBAAgB,GAAG,gBAAgB;IAC5F,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@lokal-server/ts-sdk",
+  "version": "0.1.1",
+  "description": "TypeScript SDK for Lokal external apps.",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "contracts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "vite build --watch",
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "check": "npm run typecheck && npm run lint && npm run test",
+    "contracts:update": "node scripts/update-contracts.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.0.0",
+    "eslint": "^10.5.0",
+    "globals": "^17.7.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.0",
+    "vite": "^8.1.0",
+    "vitest": "^4.1.9"
+  }
+}