@seeka-labs/cli-apps 3.7.0 → 3.8.2

package/dist/ai-context/internal/examples/v1/ivvy/README.md

@@ -0,0 +1,70 @@
+# Seeka app - Ivvy
+
+## Development
+- `yarn install`
+- `yarn watch:debug` or use VsCode debugging for "Debug Seeka App" configuration
+
+### Debugging
+Supports VSCode debugging via the debugger and utilisation of breakpoints. 
+Use "Debug Seeka App" configuration to compile, watch and start app.
+This is only tested on Linux but may work on Windows. 
+If using Windows then use WSL with an Ubuntu distro for support of attaching the VS code debugger
+
+#### Live urls
+You can expose your app locally to the internet via Ngrok to test your app before deploying.
+
+##### Setup
+1. Sign up for a Ngrok account
+2. Get your auth token
+3. `yarn ngrok config add-authtoken [auth token here]` replacing `[auth token]` with the auth token retrieved from your Ngrok dashboard
+
+##### Running
+1. `yarn start` OR start debugging in VSCode
+2. In separate terminal window run `yarn tunnel` and observe the log entry that starts with `Live url exposed` for your Seeka app webhook URL that you can place in your Seeka app configuration.
+
+### Logging
+
+Winston included - TODO
+Seq included - TODO
+
+## Deployment
+This project comes ready to deploy for free to Azure functions with database backed by Redis hosted by Upstash and queues, blobs and tables backed by Azure Storage.
+
+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/
+
+## State management
+Installations and other state is stored in Redis. Another state provider can be used, 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 swap out the connection strings with your Redis instance. 
+
+If wanting to use Upstash then create a database before following the below guide to deploying your AWS lambda function.
+- When choosing a region, consider the AWS region that the lambda function is running from to reduce latency between the function and the Redis database. 
+
+### AWS lambda function deploy
+1. [Install the aws lambda CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions)
+2. Create a function via the AWS console with following settings
+    - Mode: Author from scratch
+    - function name: `seeka-app-<your app name>`. This can match the name in your `package.json`
+    - runtime: `Node.js 18.x`
+    - architecture: `arm64`
+    - Advanced settings:
+        - Enable code signing: unchecked
+        - Enable function URL: checked
+        - Auth type: `NONE` - Calls to your function from Seeka will be validated by SHA256 signatures
+        - Invoke mode: Buffered
+        - Configure cross-origin resource sharing: unchecked
+        - Enable VPC: unchecked
+    - All other settings leave as defaults
+3. Add environment variables to the function in AWS by clicking 'Configuration' and then 'Environment varables'. Use the `.env.example` file as a reference to what variables are required by the template.
+    - For the `SELF_URL` environment variable, copy the value from the AWS console listed under `Function URL`
+4. [Authenticate the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-authentication-short-term.html)
+5. `yarn deploy`
+6. Open seeka and create your developer app, specifying the webhook URL as `<your function URL>/api/webhook/seeka/app` replacing `<your function url>` with the URL copied from the AWS console under `Function URL`
+7. Copy the App ID and App secret into your environment variables in the AWS console for your lambda function
+
+
+## References
+- https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/index.html#available-commands

package/dist/ai-context/internal/examples/v1/ivvy/_ai-summary.md

@@ -0,0 +1,32 @@
+# AI Summary for Seeka App - iVvy
+
+## Purpose and Functionality
+The iVvy app is designed to integrate with the iVvy venue management system, enabling users to track event bookings and inquiries. This app is particularly useful for managing events, venue bookings, and hospitality services.
+
+## Key Implementation Patterns
+- **Azure Functions Deployment**: The app is structured to be deployed as an Azure Function, leveraging serverless architecture for scalability and cost-effectiveness.
+- **AWS Lambda Integration**: The app can also be deployed on AWS Lambda, allowing flexibility in cloud service providers.
+- **State Management with Redis**: The app uses Redis, hosted by Upstash, for managing state, such as installations and other persistent data.
+
+## External APIs/Services Integrated
+- **iVvy API**: The core integration is with the iVvy venue management system, although specific API endpoints are not detailed in the provided files.
+- **Ngrok**: Used for exposing local development environments to the internet for testing purposes.
+- **AWS Lambda and Azure Functions**: Both platforms are supported for deploying the serverless function.
+- **Upstash Redis**: Used for state management, providing a cloud-based Redis instance.
+
+## Important Data Transformations
+- **State Management**: The app manages installation states and other data using Redis, which involves serializing and deserializing data for storage and retrieval.
+- **Environment Configuration**: The app uses environment variables for configuration, which are managed in AWS Lambda or Azure Functions settings.
+
+## Notable Code Patterns
+- **Serverless Express**: The app uses `@codegenie/serverless-express` to handle HTTP requests in a serverless environment, allowing Express.js applications to run on AWS Lambda.
+- **Logging with Winston and Seq**: Although not fully implemented, the app includes logging capabilities using Winston and Seq for structured logging.
+- **TypeScript and Esbuild**: The app is built using TypeScript, with `esbuild` used for bundling and transpiling the TypeScript code.
+- **Development and Debugging**: The app supports development workflows with tools like `nodemon` for live-reloading and VSCode debugging configurations.
+
+## Development and Deployment
+- **Development Tools**: The app uses `yarn` for package management, `eslint` for linting, and `ts-node` for running TypeScript directly.
+- **Deployment Scripts**: The app includes scripts for building and deploying to AWS Lambda and Azure Functions, with specific instructions for setting up and deploying the app.
+- **Environment Management**: `.env` files are used for managing environment variables, with examples provided for required configurations.
+
+This summary provides an overview of the iVvy app's architecture, integrations, and development patterns, which can be useful for AI assistants in understanding and referencing the app's implementation.

package/dist/ai-context/internal/examples/v1/ivvy/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "seeka-app-ivvy",
+  "version": "1.0.1",
+  "description": "Seeka app for Ivvy",
+  "repository": "https://gitlab.com/seeka-labs/app/apps/ivvy.git",
+  "author": "Seeka <platform@seeka.co>",
+  "license": "MIT",
+  "main": "./src/handler.js",
+  "private": true,
+  "engines": {
+    "node": ">=18.14.0"
+  },
+  "scripts": {
+    "lint": "eslint",
+    "build": "esbuild src/index.ts --bundle --sourcemap=external --platform=node --target=node18 --outfile=dist/index.cjs",
+    "build:aws": "esbuild src/index.ts --bundle --minify --sourcemap=external --platform=node --target=node18 --outfile=dist/index.js",
+    "watch": "tsc -w",
+    "clean": "rimraf dist && rimraf deploy.zip",
+    "start": "node --require dotenv/config dist/index.cjs",
+    "dev": "yarn run clean && yarn build && node --nolazy --require dotenv/config --inspect=5858 dist/index.cjs",
+    "tunnel": "node scripts/ngrok.cjs seeka-app-ivvy-localdev",
+    "build:aws:package": "yarn run clean && yarn run build:aws && cd dist && zip -r ../deploy.zip . && cd ..",
+    "deploy": "yarn build:aws:package && aws lambda update-function-code --function-name seeka-app-ivvy --zip-file fileb://deploy.zip && rm deploy.zip",
+    "watch:debug": "nodemon -e ts -w ./src -w .env -x yarn run dev"
+  },
+  "dependencies": {
+    "@codegenie/serverless-express": "^4.13.0",
+    "@datalust/winston-seq": "^2.0.0",
+    "@seeka-labs/sdk-apps-server": "^0.1.83",
+    "axios": "^1.6.7",
+    "express": "^4.18.2",
+    "lodash-es": "^4.17.21",
+    "luxon": "^3.4.4",
+    "node-fetch": "^3.3.2",
+    "openid-client": "^5.6.4",
+    "redis": "^4.6.12",
+    "source-map-support": "^0.5.21",
+    "winston": "^3.11.0"
+  },
+  "devDependencies": {
+    "@types/aws-lambda": "^8.10.133",
+    "@types/express": "^4.17.21",
+    "@types/lodash-es": "^4.17.12",
+    "@types/luxon": "^3.4.2",
+    "@types/node": "^18",
+    "@types/source-map-support": "^0.5.10",
+    "@typescript-eslint/eslint-plugin": "^6.19.1",
+    "@typescript-eslint/parser": "^6.19.1",
+    "dotenv": "^16.4.4",
+    "esbuild": "^0.20.0",
+    "eslint": "^8",
+    "ngrok": "^5.0.0-beta.2",
+    "nodemon": "^3.0.3",
+    "rimraf": "^5.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.4.2"
+  }
+}

package/dist/ai-context/internal/examples/v1/ivvy/src/app/index.ts

@@ -0,0 +1,31 @@
+import { Context } from 'aws-lambda';
+import express from 'express';
+import { seekaAppWebhook } from '../routes/seekaAppWebhook';
+import { ivvyWebhook } from '../routes/ivvyWebhook';
+import bodyParser from 'body-parser';
+
+const app = express();
+
+app.post('/api/webhook/seeka/app', bodyParser.text({ type: '*/*' }), async (req, res, context) => {
+    await seekaAppWebhook(req, res, context as unknown as Context);
+})
+
+app.get('/api/webhook/seeka/app', async (req, res) => {
+    res.status(404).json({ error: "Must use POST" }).send();
+})
+
+app.post('/api/webhook/ivvy', bodyParser.json({ type: '*/*' }), async (req, res, context) => {
+    await ivvyWebhook(req, res, context as unknown as Context);
+})
+
+// For local dev running
+if (!process.env.AWS_LAMBDA_FUNCTION_NAME) {
+    const startServer = async () => {
+        app.listen(4041, () => {
+            console.log("listening on port 4041!");
+        });
+    }
+    startServer();
+}
+
+export default app

package/dist/ai-context/internal/examples/v1/ivvy/src/index.ts

@@ -0,0 +1,32 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import './lib/polyfills/fetch';
+import { install } from 'source-map-support'
+import { Callback, Context, Handler } from 'aws-lambda';
+import serverlessExpress from '@codegenie/serverless-express'
+import app from './app'
+import { startServices } from './lib/services';
+import { getLogger } from './lib/logging';
+
+install({
+    environment: 'node',
+    handleUncaughtExceptions: false,
+})
+
+let serverlessExpressInstance: Handler<any, any> | null = null;
+
+async function asyncTask() {
+    await startServices(getLogger());
+}
+
+async function setup(event: any, context: Context, callback: Callback<any>) {
+    const asyncValue = await asyncTask()
+    console.log(asyncValue)
+    serverlessExpressInstance = serverlessExpress({ app })
+    return serverlessExpressInstance(event, context, callback)
+}
+
+export const handler: Handler = async (event, context, callback) => {
+    if (serverlessExpressInstance) return serverlessExpressInstance(event, context, callback)
+
+    return setup(event, context, callback)
+};

package/dist/ai-context/internal/examples/v1/ivvy/src/lib/ivvy/api/models/booking.ts

@@ -0,0 +1,114 @@
+import { IvvyUser, IvvyContact, IvvyCostCenter } from './common'
+
+// https://developer.ivvy.com/venues/getoraddbookingdata/get-booking#status
+export enum IvvyBookingStatus {
+    Hold = 1,
+    Tentative = 2,
+    Confirmed = 3,
+    Cancelled = 4,
+    Ordering = 5,
+    NotAccepted = 6,
+    ProspectiveHold = 7
+}
+
+export interface IvvyBooking {
+    accommCancellationDate: string
+    accommChargingMethod: number
+    accommCutOffDate: string
+    accommExternalBlockId: unknown
+    accommGuaranteeRequired: boolean
+    accommReservationMethod: unknown[]
+
+    // IANA
+    accountTimezone: string
+
+    additionalItems: unknown[]
+    agent: unknown
+    amountOutstanding: number
+    beoFinalisedDate: string
+    beoNumbers: unknown[]
+    beveragePackages: unknown[]
+    bookedById: number
+    bookedByUser: IvvyUser
+    bookingType: number
+    canBeMoved: boolean
+    cateringWebsiteBanner: unknown
+    cateringWebsiteBannerId: unknown
+    cateringWebsiteEndNumDays: unknown
+    cateringWebsiteEventDesc: unknown
+    cateringWebsiteLogo: unknown
+    cateringWebsiteLogoId: unknown
+    code: string
+    commissionByCostCentres: unknown[]
+    company: unknown
+    companyId: unknown
+    contact: IvvyContact
+    contactId: number
+    convertedToCancelled: string
+    convertedToConfirmed: string
+    convertedToProspectiveHold: string
+    convertedToTentative: string
+    createdDate: string
+    currentStatus: IvvyBookingStatus
+    customFields: unknown[]
+    dailyRevenue: unknown[]
+    dateAccomEnd: string
+    dateAccomStart: string
+    dateEventEnd: string
+    dateEventStart: string
+    decisionDate: string
+    eventType: string
+    eventTypeId: number
+    focRoomsDenominator: number
+    foodBeveragePayableBy: number
+    hasCateringWebsite: boolean
+    hasCommissionPaid: boolean
+    hasCommissions: boolean
+    hasPackages: boolean
+    id: number
+    isAccommIncluded: boolean
+    isBeoFinalised: boolean
+    isConfidential: boolean
+    lastModifiedDate: unknown
+    leadBccEmail: unknown
+    maxNumFocRoomsPerDay: number
+    menus: unknown[]
+    modifiedDate: string
+    name: string
+    opportunityId: unknown
+    otaFolioRef: unknown
+    packages: IvvyPackage[]
+    products: unknown[]
+    resources: unknown[]
+    revenueTemplateId: unknown
+    salesPersonUser: unknown
+    serviceFees: unknown[]
+    sessions: unknown[]
+    totalAmount: number
+    totalAttendees: number
+    totalTaxAmount: number
+    venueId: number
+
+    // IANA
+    venueTimezone: string
+}
+
+
+export interface IvvyPackage {
+    bookingDate: string
+    costcenters: IvvyCostCenter[]
+    createdDate: string
+    id: number
+    modifiedDate: string
+    numberAttendees: number
+    packageId: number
+    packageName: string
+    price: number
+    priceMethod: number
+    smallDescription: string
+    taxDetails: unknown[]
+    totalAmount: number
+    totalDiscount: number
+    totalSurcharge: number
+    totalTaxAmount: number
+}

package/dist/ai-context/internal/examples/v1/ivvy/src/lib/ivvy/api/models/common.ts

@@ -0,0 +1,49 @@
+
+export interface IvvyTax {
+    amount: number
+    costcenterId: number
+    taxId: number
+    taxRateAmount: number
+    taxRateAmountType: number
+    taxRateId: number
+}
+
+export interface IvvyAddress {
+    city: string
+    countryCode: string
+    countryName: string
+    line1: string
+    line2: string
+    line3: string
+    line4: string
+    postalCode: string
+    stateCode: string
+    stateName: string
+}
+
+export interface IvvyUser {
+    email: string
+    firstName: string
+    id: number
+    lastName: string
+    phone: string
+}
+
+export interface IvvyContact {
+    email: string
+    firstName: string
+    id: number
+    lastName: string
+    phone: string
+}
+
+export interface IvvyCostCenter {
+    costcenterId: number
+    discount: number
+    surcharge: number
+    taxDetails: unknown[]
+    totalAmount: number
+    totalSurcharge: number
+    totalTaxAmount: number
+    value: number
+}

package/dist/ai-context/internal/examples/v1/ivvy/src/lib/ivvy/api/models/invoice.ts

@@ -0,0 +1,75 @@
+import { IvvyCostCenter, IvvyContact, IvvyAddress, IvvyTax } from './common'
+
+// https://developer.ivvy.com/venues/getoraddbookingdata/get-booking#status
+export enum IvvyInvoiceStatus {
+    NotPaid = 0,
+    UnconfirmedPaid = 1,
+    Paid = 2,
+    WrittenOff = 3,
+    Cancelled = 4,
+    Refunded = 5,
+}
+
+export interface IvvyInvoice {
+    amountPaid: number
+    bookingCode: string
+    bookingId: number
+    company: unknown
+    contact: IvvyContact
+    createdDate: string
+    currency: string
+    currentStatus: IvvyInvoiceStatus
+    description: string
+    eventId: unknown
+    id: number
+    issuedDate: string
+    isTaxCharged: number
+    items: IvvyInvoiceItem[]
+    modifiedDate: string
+    paymentDueDate: string
+    payments: IvvyInvoicePayment[]
+    reference: string
+    refId: number
+    refType: number
+    refunds: unknown[]
+    taxRateUsed: unknown
+    title: string
+    toAddress: IvvyAddress
+    toContactEmail: string
+    toContactId: number
+    toContactName: string
+    totalCost: number
+    totalTaxCost: number
+    venueExTaxes: unknown[]
+    venueId: number
+}
+
+export interface IvvyInvoiceItem {
+    amountPaid: number
+    costCenters: IvvyCostCenter[]
+    description: string
+    id: number
+    quantity: number
+    ref2Id: number
+    refId: number
+    refType: number
+    taxes: IvvyTax[]
+    totalCost: number
+    totalTaxCost: number
+    unitCost: number
+}
+
+export interface IvvyInvoicePayment {
+    amountPaid: number,
+    cardType: number,
+    chequeNumber: unknown,
+    customPaymentMethodId: unknown,
+    feeAmount: number,
+    feePercentage: number,
+    id: number,
+    notes: string,
+    paidDate: string,
+    paymentId: number,
+    paymentMethod: number,
+    receiptNum: string
+}

package/dist/ai-context/internal/examples/v1/ivvy/src/lib/ivvy/api/models/webhooks.ts

@@ -0,0 +1,33 @@
+export interface IvvyWebhookPayload {
+    Type: 'SubscriptionConfirmation' | string
+    MessageId: string
+    Token: string
+    TopicArn: string
+    Message?: string
+    SubscribeURL?: string
+    Timestamp: string
+    SignatureVersion: string
+    Signature: string
+    SigningCertURL: string
+}
+
+export interface IvvyWebhookMessagePayload {
+    Subject?: IvvyWebhookMessagePayloadSubject
+    AccountId: string
+    Body: string
+    Region: string
+    Signature: string
+    SigningPublicKeyPath: string
+    SourceInfo: unknown
+    SourceType: number
+    Timestamp: number
+    TxnId: string
+}
+
+export type IvvyWebhookMessagePayloadSubject = 'BookingAdded' | 'BookingUpdated' | 'InvoiceAdded' | 'InvoiceUpdated'
+
+export interface IvvyWebhookMessagePayloadBody<TBody> {
+    data: TBody
+}
+
+export const installationIdQueryParam = 'installId'

package/dist/ai-context/internal/examples/v1/ivvy/src/lib/ivvy/api/requests.ts

@@ -0,0 +1,106 @@
+import winston, { Logger } from 'winston'
+import * as crypto from 'crypto';
+import { SeekaAppInstallState } from '../../state/seeka/installations';
+
+const ivvyApiHost = 'https://api.ap-southeast-2.ivvy.com';
+
+// https://developer.ivvy.com/getting-started/creating-the-request/signing-the-request
+function generateSignature(
+    method: string,
+    body: string,
+    contentType: string,
+    path: string,
+    apiVersion: string,
+    headers: Record<string, string>,
+    secretKey: string
+): string {
+    // Step 1: Calculate contentMd5
+    const contentMd5 = crypto.createHash('md5').update(body).digest('hex');
+
+    // Step 2: Calculate contentSign
+    const contentSign = `${contentMd5}${contentType}`;
+
+    // Step 3: Prepare ivvyHeaders
+    const ivvyHeaders = Object.keys(headers)
+        .filter(header => header.toLowerCase().startsWith('ivvy'))
+        .sort()
+        .map(header => header.toLowerCase().replace(/[-_]/g, '') + '=' + headers[header])
+        .join('&');
+
+    // Step 4: Prepare requestString
+    // const requestString = `${method}${contentSign}${date.toUTCString()}${path}${apiVersion}${ivvyHeaders}`;
+    const requestString = `${method}${contentSign}${path}${apiVersion}${ivvyHeaders}`;
+
+    // Step 5: Convert requestString to lowercase
+    const stringToSign = requestString.toLowerCase();
+
+    // Step 6: Generate HMAC-SHA1 signature
+    const signature = crypto.createHmac('sha1', secretKey).update(stringToSign).digest('hex');
+
+    return signature;
+}
+
+const getAuthorizationHeader = (
+    installation: SeekaAppInstallState,
+    method: string,
+    body: string,
+    contentType: string,
+    path: string,
+    apiVersion: string,
+    headers: Record<string, string>): string => {
+    // https://developer.ivvy.com/getting-started/creating-the-request/signing-the-request
+
+    const signature = generateSignature(method, body, contentType, path, apiVersion, headers, installation.installationSettings.ivvyApiSecret as string);
+
+    return `IWS ${installation.installationSettings.ivvyApiKey}:${signature}`
+}
+
+const formatIvvyDate = (date: Date): string => {
+    return date.toISOString().replace('T', ' ').replace('Z', '').split('.')[0]
+}
+
+export const makeIvvyApiRequest = async (path: string, body: string, method: string, contentType: string, apiVersion: string, installation: SeekaAppInstallState, logger: Logger): Promise<Response> => {
+    const now = new Date();
+    const headers = {
+        'Content-Type': contentType,
+        'IVVY-Date': formatIvvyDate(now),
+        'Content-Length': body.length.toString(),
+        'Content-MD5': crypto.createHash('md5').update(body).digest('hex'),
+    };
+
+    // trim the leading slash from the path
+    path = path.replace(/^\//, '');
+
+    // trim the last slash from the host
+    const host = ivvyApiHost.replace(/\/$/, '');
+
+    const fullPath = `/api/${apiVersion}/${path}`;
+
+    const authorizationHeader = getAuthorizationHeader(installation, method, body, contentType, fullPath, apiVersion, headers);
+    const request = {
+        headers: {
+            ...headers,
+            'X-Api-Version': apiVersion,
+            'X-Api-Authorization': authorizationHeader,
+        },
+        method,
+        body
+    }
+
+    let response: Response | null = null;
+    const fullUrl = `${host}${fullPath}`;
+    try {
+        response = await fetch(fullUrl, request);
+        if (response.status >= 400) {
+            throw new Error('Failed to make ivvy api request');
+        }
+        else {
+            logger.info('Made ivvy api request', { statusCode: response?.status, path: fullPath, fullUrl, method });
+            return response
+        }
+    }
+    catch (err) {
+        logger.error('Failed to make ivvy api request', { ex: winston.exceptions.getAllInfo(err), response: response, statusCode: response?.status, statusText: response?.statusText, fullUrl, path: fullPath, method, body: await response?.text() });
+        throw err;
+    }
+}