@seeka-labs/cli-apps 1.0.1

package/dist/init-templates/azure-function/src/lib/services/index.ts

@@ -0,0 +1,41 @@
+import winston, { Logger } from 'winston';
+
+import { connect, disconnect, isConnected } from '../state/redis';
+
+export const startServices = async (logger: Logger) => {
+    logger.debug(`Trying to connect to Redis - ${process.env.REDIS_CONNECTION_HOST}`)
+    try {
+        if (isConnected()) {
+            logger.verbose(`Redis already connected - ${process.env.REDIS_CONNECTION_HOST}`)
+        }
+        else {
+            logger.profile('service.redis.connect')
+            await connect();
+            logger.profile('service.redis.connect')
+            logger.debug(`Redis connected - ${process.env.REDIS_CONNECTION_HOST}`)
+        }
+    }
+    catch (err) {
+        logger.error(`Failed to connect to Redis - ${process.env.REDIS_CONNECTION_HOST}`, { ex: winston.exceptions.getAllInfo(err) })
+        throw err;
+    }
+}
+
+export const stopServices = async (logger: Logger) => {
+    logger.debug(`Trying to disconnect from Redis - ${process.env.REDIS_CONNECTION_HOST}`)
+    try {
+        if (isConnected() === false) {
+            logger.verbose(`Redis already disconnected - ${process.env.REDIS_CONNECTION_HOST}`)
+        }
+        else {
+            logger.profile('service.redis.disconnect')
+            await disconnect();
+            logger.profile('service.redis.disconnect')
+            logger.verbose(`Redis disconnected - ${process.env.REDIS_CONNECTION_HOST}`)
+        }
+    }
+    catch (err) {
+        logger.error(`Failed to disconnect from Redis - ${process.env.REDIS_CONNECTION_HOST}`, { ex: winston.exceptions.getAllInfo(err) })
+        throw err;
+    }
+}

package/dist/init-templates/azure-function/src/lib/state/redis/index.ts

@@ -0,0 +1,64 @@
+import { createClient } from 'redis';
+
+import { logger } from '../../logging';
+
+const redisProtocol = process.env.REDIS_CONNECTION_TLS === 'true' ? 'rediss://' : 'redis://';
+const redisConn = `${redisProtocol}${process.env.REDIS_CONNECTION_USER}:${process.env.REDIS_CONNECTION_PASSWORD}@${process.env.REDIS_CONNECTION_HOST}:${process.env.REDIS_CONNECTION_PORT}`;
+
+const redisClient = createClient({
+    url: redisConn
+})
+    .on('error', err => logger.error('Redis Client ', { error: err }));
+
+export const connect = async () => {
+    await redisClient.connect();
+}
+
+export const isConnected = () => {
+    return redisClient.isOpen;
+}
+
+export const disconnect = async () => {
+    await redisClient.disconnect();
+}
+
+const getKeyPrefix = (stateType: string) => `seeka:app:${process.env.SEEKA_APP_ID}:${stateType}`
+const getKey = (stateType: string, key: string) => `${getKeyPrefix(stateType)}:${key}`
+
+export async function getOrCreate<TState>(stateType: string, key: string, toCreate: TState): Promise<TState> {
+    const fullKey = getKey(stateType, key);
+    const existingStr = await redisClient.get(fullKey);
+    if (existingStr) return JSON.parse(existingStr);
+
+    await redisClient.set(fullKey, JSON.stringify(toCreate));
+
+    return toCreate;
+}
+
+export async function tryGet<TState>(stateType: string, key: string): Promise<TState | null> {
+    const fullKey = getKey(stateType, key);
+    const existingStr = await redisClient.get(fullKey);
+    if (existingStr) return JSON.parse(existingStr);
+
+    return null;
+}
+
+export async function getList<TState>(stateType: string): Promise<TState[]> {
+    const prefix = getKeyPrefix(stateType);
+    const allKeys = await redisClient.keys(`${prefix}:*`);
+    const listStr = await redisClient.mGet(allKeys);
+
+    if (listStr) return listStr.filter(e => Boolean(e)).map(e => JSON.parse(e as string));
+
+    return [];
+}
+
+export async function set<TState>(stateType: string, key: string, toCreate: TState): Promise<void> {
+    const fullKey = getKey(stateType, key);
+    await redisClient.set(fullKey, JSON.stringify(toCreate));
+}
+
+export async function remove(stateType: string, key: string): Promise<void> {
+    const fullKey = getKey(stateType, key);
+    await redisClient.del(fullKey);
+}

package/dist/init-templates/azure-function/src/lib/state/seeka/installations.ts

@@ -0,0 +1,67 @@
+import type { Logger } from 'winston';
+
+import { getList, remove, set, tryGet } from '../redis';
+
+export interface SeekaAppInstallState {
+    /** ID of the organisation that installed the app */
+    organisationId: string;
+    /** ID of the brand that installed the app */
+    organisationBrandId: string;
+    /** ID of the installation of the app */
+    applicationInstallId: string;
+    // Installation settings provided by the user installing the app
+    installationSettings: SampleAppInstallSettings
+    // State relating to the app and installation of the app
+    installationState: SampleAppInstallState;
+
+    // When the app was installed
+    installedAt: string; // new Date().toISOString()
+}
+
+export interface SampleAppInstallState {
+    stateItem1?: string
+    stateItem2?: string
+    grantedPermissions?: string[]
+}
+
+export type SampleAppInstallSettings = { [key: string]: any; } | {
+    myAppInstallSetting1: string | number | undefined;
+    myAppInstallSetting2: string | number | undefined;
+}
+
+const stateType = 'install'
+
+export const tryGetInstallation = async (applicationInstallId: string, throwWhenNotFound: boolean, logger: Logger): Promise<SeekaAppInstallState | null> => {
+    const installation = await tryGet<SeekaAppInstallState>(stateType, applicationInstallId);
+    if (installation == null && throwWhenNotFound) {
+        throw new Error(`Seeka installation ${applicationInstallId} not found`);
+    }
+
+    return installation;
+}
+
+export const listInstallations = async (logger: Logger): Promise<SeekaAppInstallState[]> => {
+    const installations = await getList<SeekaAppInstallState>(stateType);
+
+    return installations;
+}
+
+
+export const createOrUpdateInstallation = async (state: SeekaAppInstallState, logger: Logger): Promise<SeekaAppInstallState> => {
+    if (!state.installationState) state.installationState = {};
+    if (!state.installedAt) state.installedAt = new Date().toISOString();
+
+    const creating = (await tryGetInstallation(state.applicationInstallId, false, logger)) === null;
+
+    await set(stateType, state.applicationInstallId, state);
+
+    logger.info(creating ? 'Created installation state' : 'Updated installation state', { applicationInstallId: state.applicationInstallId, organisationId: state.organisationId, organisationBrandId: state.organisationBrandId });
+
+    return state;
+}
+
+export const deleteInstallation = async (applicationInstallId: string, logger: Logger): Promise<void> => {
+    await remove(stateType, applicationInstallId);
+
+    logger.info('Deleted installation state', { applicationInstallId });
+}

package/dist/init-templates/azure-function/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": false,
+    "esModuleInterop": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "sourceMap": true,
+    "module": "CommonJS",
+    "target": "ES6",
+    "resolveJsonModule": true,
+    "isolatedModules": false,
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}

package/dist/init-templates/netlify-function/.env.example

@@ -0,0 +1,18 @@
+SEEKA_APP_ID=
+SEEKA_APP_SECRET=
+SEEKA_DEBUG_ENABLED=true
+SEEKA_INGEST_URL=
+SEEKA_ISSUER_URL=
+NODE_TLS_REJECT_UNAUTHORIZED=1
+NETLIFY_ENABLED=false
+NETLIFY_SITE_NAME=
+REDIS_CONNECTION_USER=default
+REDIS_CONNECTION_PASSWORD=
+REDIS_CONNECTION_TLS=true
+REDIS_CONNECTION_HOST=
+REDIS_CONNECTION_PORT=
+LOGGING_SEQ_SERVERURL=
+LOGGING_SEQ_APIKEY=
+LOGGING_LEVEL=silly
+ENCRYPTION_SECRET=
+INBOUND_HTTP_CALL_API_KEY=

package/dist/init-templates/netlify-function/.eslintrc.cjs

@@ -0,0 +1,7 @@
+/* eslint-env node */
+module.exports = {
+    extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
+    parser: '@typescript-eslint/parser',
+    plugins: ['@typescript-eslint'],
+    root: true,
+};

package/dist/init-templates/netlify-function/.example.gitignore

@@ -0,0 +1,36 @@
+# Local Netlify folder
+.netlify
+.env
+
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+# testing
+/coverage
+
+# production
+/build
+/dist
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo

package/dist/init-templates/netlify-function/.vscode/launch.json

@@ -0,0 +1,45 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "netlify dev",
+      "type": "node",
+      "request": "launch",
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
+      "outFiles": [
+        "${workspaceFolder}/.netlify/functions-serve/**/*.js"
+      ],
+      "program": "${workspaceFolder}/node_modules/.bin/netlify",
+      "args": [
+        "dev"
+      ],
+      "console": "integratedTerminal",
+      "env": {
+        "BROWSER": "none"
+      },
+      "serverReadyAction": {
+        "pattern": "Server now ready on (https?://[\\w:.-]+)",
+        "uriFormat": "%s",
+        "action": "debugWithChrome"
+      }
+    },
+    {
+      "name": "netlify functions:serve",
+      "type": "node",
+      "request": "launch",
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
+      "outFiles": [
+        "${workspaceFolder}/.netlify/functions-serve/**/*.js"
+      ],
+      "program": "${workspaceFolder}/node_modules/.bin/netlify",
+      "args": [
+        "functions:serve"
+      ],
+      "console": "integratedTerminal"
+    }
+  ]
+}

package/dist/init-templates/netlify-function/README.md

@@ -0,0 +1,60 @@
+# Seeka app - Netlify functions
+
+## Development
+
+- `yarn install`
+- `yarn dev`
+
+### Dependencies
+- Python >=3.6.0 - https://www.python.org/downloads/ or `choco install python`
+
+### Invoking functions
+Run `yarn dev:netlify:invoke:polling-example-job-scheduled` to trigger scheduled job which triggers multiple background jobs, 1 for each installation of the app
+
+### Debugging / local development before deployment
+- This template uses [Netlify's live url debugging](https://answers.netlify.com/t/netlify-dev-with-support-for-custom-live-urls/101261)
+- Supports VSCode debugging - See `.vscode/launch.json`. This is only supported on Linux. If using Windows then use WSL with an Ubuntu distro for support of attaching the VS code debugger
+
+## Logging
+Centralised logging handled by [Winston](https://www.npmjs.com/package/winston). Winston is installed in this template and is also used in the Seeka SDK NPM packages.
+
+[Seq](https://datalust.co/seq) Winston transport is installed in this template (optional).
+
+To configure Seq options, see `_SEQ_` environment variables.
+
+To install Seq on your development machine
+1. Run `docker run --name seq -d --restart=always -e ACCEPT_EULA=Y -p 5341:80 datalust/seq:2024.2`
+2. Update your `LOGGING_SEQ_SERVERURL` environment variable to `http://localhost:5341` or `http://[YOUR MACHINE NAME].local:5341` if using WSL.
+
+## State management
+Installations of your app and other state required for your app to function is stored in Redis. Another state provider can be swapped out for Redis, see `src/lib/state/seeka/installations.ts` for the file that manages the state of the installations.
+
+### Upstash (optional)
+If you dont want to use Upstash for Redis then the connection strings in `.env` can be swapped with your Redis instance. 
+
+> If using Upstash then create a database before following the below guide to deploying your Netlify function.
+
+> When choosing region - use US East (Ohio) - us-east-* as this is the same AWS region that the free Netlify functions run from. If not on the Netlify free plan, select the closest Upstash region that your Netlify function is hosted in to reduce latency between the function and the Redis database. 
+
+> Considerations - max connection limit (1000) of Upstash connections in relation to concurrent execution count of the Netlify functions
+
+## Deployment
+This project comes ready to deploy for free to Netlify with a database and queues backed by Redis hosted by Upstash. 
+
+At the point of writing, Netlify and Upstash can be used to deploy your app for free.
+- https://upstash.com/pricing
+- https://www.netlify.com/pricing/
+
+### Deployment to Netlify
+#### From your local machine
+- `yarn deploy`
+
+#### Using Netlify continuous delivery
+See the [Netlify docs](https://docs.netlify.com/functions/deploy/?fn-language=ts)
+
+## Considerations when using this template
+Each call to the netlify function will create a new connection to the database/Redis as calls to the Netlify function in quick succession will not share a single "warm" function host which is supported by Azure Functions and AWS Lambda.
+
+## References
+- https://docs.netlify.com/cli/get-started/
+- https://docs.netlify.com/functions/get-started/?fn-language=ts

package/dist/init-templates/netlify-function/netlify.toml

@@ -0,0 +1,7 @@
+[functions]
+  directory = "src/api"
+  node_bundler = "esbuild"
+
+[dev]
+  command = "yarn dev"
+  port = 8888

package/dist/init-templates/netlify-function/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "seeka-app-example-name",
+  "version": "0.0.1",
+  "description": "Seeka example app for hosting on Netlify functions",
+  "author": "Seeka <platform@seeka.co>",
+  "license": "MIT",
+  "type": "module",
+  "private": true,
+  "engines": {
+    "node": ">=18.14.0"
+  },
+  "scripts": {
+    "dev:invoke:example-scheduled-job": "netlify functions:invoke --name polling-example-job-scheduled --port 8888 --identity",
+    "lint": "eslint",
+    "dev": "netlify dev --live=localdev --port 8888 --no-open",
+    "build": "netlify functions:build --functions=dist --src=src/api",
+    "deploy": "netlify deploy --build --skip-functions-cache --prod"
+  },
+  "dependencies": {
+    "@datalust/winston-seq": "^2.0.0",
+    "@netlify/functions": "^2.5.1",
+    "@seeka-labs/sdk-apps-server": "^1.0.1",
+    "axios": "^1.6.7",
+    "lodash-es": "^4.17.21",
+    "openid-client": "^5.6.4",
+    "redis": "^4.6.12",
+    "winston": "^3.11.0"
+  },
+  "devDependencies": {
+    "@types/lodash-es": "^4.17.12",
+    "@types/node": "^18",
+    "@typescript-eslint/eslint-plugin": "^6.19.1",
+    "@typescript-eslint/parser": "^6.19.1",
+    "eslint": "^8",
+    "netlify-cli": "^17.15.3",
+    "typescript": "^5.3.3"
+  }
+}

package/dist/init-templates/netlify-function/src/api/example-job-background/index.ts

@@ -0,0 +1,52 @@
+import winston, { Logger } from 'winston';
+
+import {
+    apiKeyHeaderName, BackgroundJobRequestContext, jobNames, signatureHeaderName, validateApiKey,
+    validateSignature
+} from '@/lib/jobs';
+import { backgroundJobLogger } from '@/lib/logging';
+import { startServices, stopServices } from '@/lib/services';
+
+import type { Config, Context } from "@netlify/functions"
+export default async (req: Request, context: Context) => {
+    if (req.method != "POST") {
+        return new Response("Method not allowed", { status: 405 });
+    }
+
+    const bodyStr = await req.text();
+    const body = JSON.parse(bodyStr) as BackgroundJobRequestContext;
+    const logger = backgroundJobLogger(jobNames.exampleBackgroundJob, body, context);
+    logger.profile(`job.${jobNames.exampleBackgroundJob}`)
+
+    await startServices(logger);
+
+    if (process.env.SEEKA_DEBUG_ENABLED === 'true') {
+        logger.info('Received request to trigger background job', { body, headers: req.headers });
+    }
+    else {
+        logger.verbose('Received request to trigger background job', { body });
+    }
+
+    try {
+        // Verify request
+        validateApiKey(req.headers.get(apiKeyHeaderName) as string, logger);
+        validateSignature(req.headers.get(signatureHeaderName) as string, bodyStr, logger);
+
+        // Execute
+        await doWork(body, logger);
+
+        // Close db connections
+        await stopServices(logger);
+    }
+    catch (err) {
+        logger.error('Error executing background job', { ex: winston.exceptions.getAllInfo(err) })
+    }
+
+    logger.profile(`job.${jobNames.exampleBackgroundJob}`)
+
+    return new Response(undefined, { status: 202 })
+}
+
+const doWork = async (context: BackgroundJobRequestContext, logger: Logger) => {
+    logger.info('Ran background job')
+}

package/dist/init-templates/netlify-function/src/api/polling-example-job-scheduled/index.ts

@@ -0,0 +1,46 @@
+import winston from 'winston';
+
+import { jobNames, triggerBackgroundJob } from '@/lib/jobs';
+import { backgroundJobLogger } from '@/lib/logging';
+import { startServices, stopServices } from '@/lib/services';
+import { listInstallations } from '@/lib/state/seeka/installations';
+
+import type { Config, Context } from "@netlify/functions"
+export const config: Config = {
+    schedule: "@hourly"
+}
+
+export default async (req: Request, context: Context) => {
+    const { next_run } = (await req.json()) as { next_run: string }
+
+    const logger = backgroundJobLogger(jobNames.examplePollingScheduledJob, undefined, context);
+
+    logger.profile(`job.${jobNames.examplePollingScheduledJob}`)
+    if (process.env.SEEKA_DEBUG_ENABLED === 'true') {
+        logger.info('Received request to trigger scheduled job', { headers: req.headers, next_run });
+    }
+    else {
+        logger.verbose('Received request to trigger scheduled job', { next_run });
+    }
+
+    await startServices(logger);
+
+    const allInstallations = await listInstallations(logger);
+    logger.verbose(`Triggering background job for ${allInstallations.length} installations`, { allInstallations })
+
+    // Close db connections
+    await stopServices(logger);
+
+    const promises = allInstallations.map(installation => triggerBackgroundJob(jobNames.exampleBackgroundJob, installation, logger))
+
+    try {
+        await Promise.all(promises);
+    }
+    catch (err) {
+        logger.error('Error triggering background jobs', { ex: winston.exceptions.getAllInfo(err) })
+    }
+
+    logger.profile(`job.${jobNames.examplePollingScheduledJob}`)
+
+    return new Response(undefined, { status: 202 })
+}