@aravinthan_p/appnest-app-sdk-utils 0.0.1

package/appnestFunctions/appnestFunctions.MD

@@ -0,0 +1,163 @@
+# Appnest SDK Functions — Developer Reference
+
+This document is the **single source of truth** for the Appnest custom SDK functions. Use it for **code generation**, auto-completion, and integration in your app.
+
+**For code generation:** This file is self-contained. All function signatures, parameters, types, and constraints are below; no other MD files are required to generate code that calls these SDK functions.
+
+**Do not add `@aravinthan_p/appnest-app-sdk-utils` (or `appnest-app-sdk-utils`) to `app-backend/package.json`.** The SDK is provided by the AppNest platform at runtime. Your backend code should `require('@aravinthan_p/appnest-app-sdk-utils')` (or the package name configured by the platform) without listing it as a dependency.
+
+---
+
+## Import
+
+```javascript
+const AppnestFunctions = require('appnest-app-sdk-utils');
+// or from path:
+// const AppnestFunctions = require('<path-to-sdk>/appnestFunctions');
+
+const { $db, $file, $http, $next, $schedule, getTraceId } = AppnestFunctions;
+```
+
+---
+
+## Quick reference
+
+| Module      | Purpose                    | Main APIs / Methods |
+|------------|----------------------------|----------------------|
+| **$db**    | Key/value storage          | `get`, `create`, `update`, `delete`; typed: `string`, `number`, `list`, `map`, `boolean` (each with get/create/update/delete and type-specific ops) |
+| **$http**  | Outbound HTTP requests     | `request({ url, method, headers, body, query })` |
+| **$file**  | File storage (signed URLs) | `getUploadUrl`, `getDownloadUrl`, `delete`, `list`, `exists` |
+| **$next**  | Invoke another function    | `run({ functionName, payload, delay })` |
+| **$schedule** | Scheduled jobs          | `create`, `get`, `update`, `pause`, `resume`, `delete` |
+| **getTraceId** | Request trace ID       | `getTraceId()` → string (for logging/correlation) |
+
+---
+
+## Module details (per-function docs)
+
+Each module has a dedicated MD file with full signatures, parameters, and examples. Paths are relative to `appnestFunctions/`:
+
+| Module    | Doc file              | Summary |
+|-----------|------------------------|--------|
+| **$db**   | [dbFunction/db.MD](dbFunction/db.MD) | Key/value by type: STRING, NUMBER, LIST, MAP, BOOLEAN. Common param: `key` (string). |
+| **$http** | [httpFunction/http.MD](httpFunction/http.MD) | `$http.request({ url, method, headers, body, query })`. Methods: GET, POST, PUT, DELETE, PATCH. Use `<%=iparams.<key>%>` for manifest params; use `<%=user_oauth.access_token%>` in headers for platform's access_token (e.g. OAuth or API auth); framework replaces at runtime. |
+| **$file** | [fileFunction/file.MD](fileFunction/file.MD) | `getUploadUrl`, `getDownloadUrl`, `delete`, `list`, `exists`. Params: `path`, `visibility` (optional). |
+| **$next** | [nextFunction/next.MD](nextFunction/next.MD) | `$next.run({ functionName, payload, delay })`. Delay in seconds. |
+| **$schedule** | [scheduleFunction/schedule.MD](scheduleFunction/schedule.MD) | Types: ONE_TIME, CRON, RECURRING. `name`, `type`, `data` required; type-specific: `runAt`, `cronExpression`, or `repeat`. |
+
+---
+
+## Code reference — function signatures & param details
+
+All functions return `Promise<{ data, status }>` unless noted.
+
+---
+
+### $db
+
+**Common param for all $db methods:** `key` (string, required, non-empty, max 1000 chars).
+
+| Function | Params | Types / constraints |
+|----------|--------|----------------------|
+| `$db.get({ key })` | key | string |
+| `$db.create({ key })` | key | string |
+| `$db.update({ key, value })` | key, value | key: string; value: string |
+| `$db.delete({ key })` | key | string |
+| `$db.string.get({ key })` | key | string |
+| `$db.string.create({ key, value })` | key, value | key: string; value: string |
+| `$db.string.update({ key, value })` | key, value | string, string |
+| `$db.string.delete({ key })` | key | string |
+| `$db.number.get({ key })` | key | string |
+| `$db.number.create({ key, value })` | key, value | key: string; value: number |
+| `$db.number.update({ key, value })` | key, value | string, number |
+| `$db.number.delete({ key })` | key | string |
+| `$db.number.increment({ key })` | key | string |
+| `$db.number.decrement({ key })` | key | string |
+| `$db.list.get({ key })` | key | string |
+| `$db.list.create({ key, value })` | key, value | key: string; value: array |
+| `$db.list.update({ key, value })` | key, value | string, array |
+| `$db.list.append({ key, value })` | key, value | string, array |
+| `$db.list.prepend({ key, value })` | key, value | string, array |
+| `$db.list.updateItemAtIndex({ key, value, index })` | key, value, index | string, array, number |
+| `$db.list.removeItemAtIndex({ key, index })` | key, index | string, number |
+| `$db.map.get({ key })` | key | string |
+| `$db.map.create({ key, value })` | key, value | key: string; value: object (JSON-serializable) |
+| `$db.map.update({ key, value })` | key, value | string, object |
+| `$db.map.delete({ key })` | key | string |
+| `$db.boolean.get({ key })` | key | string |
+| `$db.boolean.create({ key, value })` | key, value | key: string; value: boolean |
+| `$db.boolean.update({ key, value })` | key, value | string, boolean |
+| `$db.boolean.delete({ key })` | key | string |
+
+---
+
+### $http
+
+| Function | Params | Types / constraints |
+|----------|--------|----------------------|
+| `$http.request({ url, query, method, headers, body })` | url, query, method, headers, body | **url** (string, required): must start with `http://` or `https://`, max 2048 chars. **method** (string, required): `GET` \| `POST` \| `PUT` \| `DELETE` \| `PATCH`. **headers** (object, required): string key/value, max 1000 keys, each value max 1000 chars. **body** (object, required): same. **query** (object, required): same. **Runtime replacement:** Use `<%=iparams.<key>%>` for manifest params; use `<%=user_oauth.access_token%>` in headers for platform's access_token (e.g. OAuth or API auth); AppNest framework replaces at runtime. See [http.MD](httpFunction/http.MD). |
+
+---
+
+### $file
+
+**Common params:** `path` (string, required), `visibility` (string, optional, default `"PUBLIC"`: `"PUBLIC"` \| `"PRIVATE"`).
+
+| Function | Params | Notes |
+|----------|--------|--------|
+| `$file.getUploadUrl({ path, visibility })` | path, visibility | Signed URL for upload. |
+| `$file.getDownloadUrl({ path, visibility })` | path, visibility | Signed URL for download/read. |
+| `$file.delete({ path, visibility })` | path, visibility | Delete file at path. |
+| `$file.list({ path, visibility })` | path, visibility | List objects under path. |
+| `$file.exists({ path, visibility })` | path, visibility | Check if file exists. |
+
+---
+
+### $next
+
+| Function | Params | Types / constraints |
+|----------|--------|----------------------|
+| `$next.run({ functionName, payload, delay })` | functionName, payload, delay | **functionName** (string, required). **payload** (object, required). **delay** (number, optional, default 0): seconds before execution, >= 0. |
+
+---
+
+### $schedule
+
+**Common for create/update:** `name` (string, required, max 30), `type` (string, required: `ONE_TIME` \| `CRON` \| `RECURRING`), `data` (object, required, at least one key).
+
+| Function | Params | Types / constraints |
+|----------|--------|----------------------|
+| `$schedule.create({ name, type, data, runAt? \| cronExpression? \| repeat? })` | name, type, data + type-specific | **ONE_TIME:** `runAt` (string, required, valid date e.g. ISO 8601). **CRON:** `cronExpression` (string, required). **RECURRING:** `repeat: { frequency, timeUnit }` — frequency (integer >= 1; >= 10 if timeUnit is MINUTES), timeUnit: `MINUTES` \| `HOURS` \| `DAYS` \| `WEEKS` \| `MONTHS` \| `YEARS`. |
+| `$schedule.get({ name, type })` | name, type | name: string; type: ONE_TIME \| CRON \| RECURRING |
+| `$schedule.update({ name, type, data, runAt? \| cronExpression? \| repeat? })` | same as create | Same type-specific rules as create. |
+| `$schedule.pause({ name, type })` | name, type | string, string |
+| `$schedule.resume({ name, type })` | name, type | string, string |
+| `$schedule.delete({ name, type })` | name, type | string, string |
+
+---
+
+### getTraceId
+
+| Function | Params | Return |
+|----------|--------|--------|
+| `getTraceId()` | none | string (trace ID for logging/correlation) |
+
+---
+
+## Usage in handlers
+
+Typical pattern inside a Lambda or handler:
+
+```javascript
+const { $db, $http, $file, $next, $schedule, getTraceId } = require('appnest-app-sdk-utils');
+
+exports.myHandler = async (event, context) => {
+  const traceId = getTraceId();
+  // Use $db, $http, $file, $next, $schedule as needed
+  const row = await $db.string.get({ key: 'config' });
+  await $http.request({ url: 'https://api.example.com', method: 'GET', headers: {}, body: {}, query: {} });
+  await $next.run({ functionName: 'otherFn', payload: { id: 1 }, delay: 0 });
+};
+```
+
+**Code generation:** Use this single file as the only input; it contains all SDK function names, signatures, and param details needed to generate correct calls to `$db`, `$http`, `$file`, `$next`, `$schedule`, and `getTraceId`.

package/appnestFunctions/dbFunction/db.MD

@@ -0,0 +1,161 @@
+# $db — Key/Value Database SDK
+
+The `$db` module provides typed key/value storage operations. Use the namespaced APIs (`$db.string`, `$db.number`, `$db.list`, `$db.map`, `$db.boolean`) for full create/update support.
+
+---
+
+## Import / Usage
+
+```javascript
+const { $db } = require('<path-to-sdk>/appnestFunctions');
+// or from appnest-app-sdk-utils
+const { $db } = require('appnest-app-sdk-utils');
+```
+
+---
+
+## Common Rules
+
+| Parameter | Type   | Required | Constraints                          |
+|----------|--------|----------|--------------------------------------|
+| `key`    | string | yes      | Non-empty, max 1000 characters       |
+
+**Return shape:** `Promise<{ data, status }>`
+
+---
+
+## Data Types
+
+| Type     | Description                    |
+|----------|--------------------------------|
+| STRING   | string value                   |
+| NUMBER   | number value                   |
+| LIST     | array value                    |
+| MAP      | JSON object (non-array)        |
+| BOOLEAN  | boolean value                  |
+
+---
+
+## Top-level (string-oriented)
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| get    | `$db.get({ key })` | Get value by key (string) |
+| create | `$db.create({ key })` | Create key (string; for full control use `$db.string.create`) |
+| update | `$db.update({ key, value })` | Update string value |
+| delete | `$db.delete({ key })` | Delete by key |
+
+**Example:**
+
+```javascript
+const result = await $db.get({ key: 'welcome' });
+await $db.update({ key: 'welcome', value: 'hello' });
+await $db.delete({ key: 'welcome' });
+```
+
+---
+
+## $db.string
+
+| Method | Signature | Parameters |
+|--------|-----------|------------|
+| get    | `$db.string.get({ key })` | `key` (string, required) |
+| create | `$db.string.create({ key, value })` | `key`, `value` (string, required) |
+| update | `$db.string.update({ key, value })` | `key`, `value` (string, required) |
+| delete | `$db.string.delete({ key })` | `key` (string, required) |
+
+**Example:**
+
+```javascript
+await $db.string.create({ key: 'welcome', value: 'hello' });
+const res = await $db.string.get({ key: 'welcome' });
+await $db.string.update({ key: 'welcome', value: 'hello world' });
+await $db.string.delete({ key: 'welcome' });
+```
+
+---
+
+## $db.number
+
+| Method    | Signature | Parameters |
+|-----------|-----------|------------|
+| get       | `$db.number.get({ key })` | `key` (string, required) |
+| create    | `$db.number.create({ key, value })` | `key`, `value` (number, required) |
+| update    | `$db.number.update({ key, value })` | `key`, `value` (number, required) |
+| delete    | `$db.number.delete({ key })` | `key` (string, required) |
+| increment | `$db.number.increment({ key })` | `key` (string, required) |
+| decrement | `$db.number.decrement({ key })` | `key` (string, required) |
+
+**Example:**
+
+```javascript
+await $db.number.create({ key: 'counter', value: 0 });
+const res = await $db.number.get({ key: 'counter' });
+await $db.number.increment({ key: 'counter' });
+await $db.number.decrement({ key: 'counter' });
+await $db.number.delete({ key: 'counter' });
+```
+
+---
+
+## $db.list
+
+| Method            | Signature | Parameters |
+|-------------------|-----------|------------|
+| get               | `$db.list.get({ key })` | `key` (string, required) |
+| create            | `$db.list.create({ key, value })` | `key`, `value` (array, required) |
+| update            | `$db.list.update({ key, value })` | `key`, `value` (array, required) |
+| append            | `$db.list.append({ key, value })` | `key`, `value` (array, required) |
+| prepend           | `$db.list.prepend({ key, value })` | `key`, `value` (array, required) |
+| updateItemAtIndex | `$db.list.updateItemAtIndex({ key, value, index })` | `key`, `value` (array), `index` (number, required) |
+| removeItemAtIndex | `$db.list.removeItemAtIndex({ key, index })` | `key`, `index` (number, required) |
+
+**Example:**
+
+```javascript
+await $db.list.create({ key: 'logs', value: [] });
+await $db.list.append({ key: 'logs', value: ['entry-1'] });
+const res = await $db.list.get({ key: 'logs' });
+await $db.list.removeItemAtIndex({ key: 'logs', index: 0 });
+await $db.delete({ key: 'logs' });
+```
+
+---
+
+## $db.map
+
+| Method | Signature | Parameters |
+|--------|-----------|------------|
+| get    | `$db.map.get({ key })` | `key` (string, required) |
+| create | `$db.map.create({ key, value })` | `key`, `value` (object, required, JSON-serializable) |
+| update | `$db.map.update({ key, value })` | `key`, `value` (object, required) |
+| delete | `$db.map.delete({ key })` | `key` (string, required) |
+
+**Example:**
+
+```javascript
+await $db.map.create({ key: 'profile', value: { name: 'Ava', age: 28 } });
+const res = await $db.map.get({ key: 'profile' });
+await $db.map.update({ key: 'profile', value: { name: 'Ava', age: 29 } });
+await $db.map.delete({ key: 'profile' });
+```
+
+---
+
+## $db.boolean
+
+| Method | Signature | Parameters |
+|--------|-----------|------------|
+| get    | `$db.boolean.get({ key })` | `key` (string, required) |
+| create | `$db.boolean.create({ key, value })` | `key`, `value` (boolean, required) |
+| update | `$db.boolean.update({ key, value })` | `key`, `value` (boolean, required) |
+| delete | `$db.boolean.delete({ key })` | `key` (string, required) |
+
+**Example:**
+
+```javascript
+await $db.boolean.create({ key: 'isActive', value: true });
+const res = await $db.boolean.get({ key: 'isActive' });
+await $db.boolean.update({ key: 'isActive', value: false });
+await $db.boolean.delete({ key: 'isActive' });
+```