@seeka-labs/cli-apps 3.7.0 → 3.8.2

package/dist/ai-context/internal/examples/v2/navitas/app/server/src/lib/salesforce/opportunities/index.ts

@@ -0,0 +1,193 @@
+import { ContentItemActivityTrackingEventMetadata, PersonIdentifiers, SeekaAppHelper, TrackingEventSourceOriginType, separatePersonFullName } from "@seeka-labs/sdk-apps-server";
+import { Logger } from "winston";
+import * as packageJson from '../../../../package.json';
+import { createOrUpdateJourney, getJourneyIdFromOpportunity, handleContactMerge, tryGetJourney } from "../../state/navitas/journey";
+import { SeekaAppInstallState } from "../../state/seeka/installations";
+import { handleJourneyStageTransition } from "../journeys";
+import { SalesforceOpportunityWebhookPayloadObject, getWhoId, lookupOpportunityStage } from "../models";
+
+export const handleSalesforceOpportunityWebhook = async (opportunityPayload: SalesforceOpportunityWebhookPayloadObject, installation: SeekaAppInstallState, logger: Logger): Promise<void> => {
+    if (!opportunityPayload) {
+        logger.error('No opportunity object found in Salesforce webhook payload');
+        return;
+    }
+
+    logger.info('Handling Salesforce Opportunity webhook', { opportunityPayload });
+    const opportunityId = opportunityPayload.Id;
+    if (!opportunityId) {
+        logger.error('No opportunity id found in Salesforce webhook payload');
+        return;
+    }
+    let thisLogger = logger.child({ opportunityId: opportunityId });
+
+    // Create seeka API helper
+    const { name, version } = packageJson;
+    const helper = SeekaAppHelper.create(process.env['SEEKA_APP_SECRET'] as string, {
+        organisationId: installation.organisationId as string,
+        applicationInstallId: installation.applicationInstallId as string,
+        applicationId: process.env['SEEKA_APP_ID'] as string,
+    }, { name, version }, installation.installationState.grantedPermissions, thisLogger);
+
+    let seekaProfileId = opportunityPayload.Account_Seeka_Profile_Id__c || null;
+    let whoId = getWhoId(opportunityPayload.ContactId, undefined, thisLogger);
+    thisLogger = thisLogger.child({ whoId });
+    const seekaProfile = salesforceOpportunityToSeekaProfile(opportunityPayload, whoId);
+    if (!seekaProfileId) {
+        thisLogger.warn('No Seeka profile ID found in Salesforce opportunity, creating Seeka profile', { opportunityId, opportunityPayload });
+        seekaProfileId = await helper.api.mergeIdentity(seekaProfile, {
+            origin: TrackingEventSourceOriginType.Server
+        })
+        thisLogger = thisLogger.child({ Person_PersonId: seekaProfileId });
+        thisLogger.info('Created Seeka profile for Salesforce opportunity', { opportunityId, seekaProfileId });
+    }
+    else {
+        thisLogger = thisLogger.child({ Person_PersonId: seekaProfileId });
+
+        seekaProfile.seekaPId = seekaProfileId;
+        await helper.api.mergeIdentity(seekaProfile, {
+            origin: TrackingEventSourceOriginType.Server
+        })
+
+        thisLogger.info('Used existing Seeka profile ID for Salesforce opportunity and updated Seeka profile', { opportunityId, seekaProfileId });
+    }
+
+    const opportunityPayloadStage = lookupOpportunityStage(opportunityPayload.StageName);
+    const journeyId = await getJourneyIdFromOpportunity(opportunityPayload, thisLogger);
+    if (!journeyId) {
+        thisLogger.error('No journeyId found in opportunity', { opportunityPayload, opportunityId, seekaProfile, seekaProfileId });
+        return;
+    }
+    thisLogger = thisLogger.child({ journeyId });
+    let journey = await tryGetJourney(journeyId, false, thisLogger);
+    let created = false;
+    if (!whoId && journey && journey.whoId) {
+        thisLogger.warn('No whoID found on webhook payload but exists on journey')
+        whoId = journey.whoId;
+        thisLogger = thisLogger.child({ whoId });
+    }
+
+    if (!journey) {
+        thisLogger.warn('No journey found for Salesforce opportunity, creating journey. There should be one already created as a result of the initial lead', { opportunityId, opportunityPayload });
+
+        // Create journey in state
+        journey = await createOrUpdateJourney({
+            journeyId,
+            opportunityId,
+            whoId,
+            opportunity: opportunityPayload,
+            contactId: opportunityPayload.ContactId,
+            opportunityPreviousStage: undefined,
+            opportunityCurrentStage: opportunityPayloadStage,
+            seekaPersonId: [seekaProfileId]
+        }, false, true, thisLogger);
+        created = true;
+    }
+    const previousStage = { ...journey.opportunityCurrentStage };
+    if (!created) {
+        // Update opportunity
+        if (journey.whoId && whoId && journey.whoId !== whoId) {
+            thisLogger.warn('Updating WhoId on journey', { prev: journey.whoId, updated: whoId })
+        }
+
+        const oldContactId = journey.contactId;
+        journey = await createOrUpdateJourney({
+            ...journey,
+            whoId: whoId || journey.whoId,
+            opportunity: opportunityPayload,
+            opportunityPreviousStage: previousStage,
+            contactId: opportunityPayload.ContactId || journey.contactId,
+            opportunityCurrentStage: opportunityPayloadStage,
+            seekaPersonId: [...(journey.seekaPersonId || []), seekaProfileId].filter(Boolean)
+        }, false, true, thisLogger);
+
+        await handleContactMerge(oldContactId, opportunityPayload.ContactId, whoId || journey.whoId, 'opportunity', opportunityPayload.Id, installation, thisLogger)
+    }
+    thisLogger = thisLogger.child({ 'Person_PersonId': seekaProfileId, 'Person_BrowserId': journey.seekaPersonId, opportunityId: journey.opportunityId, leadId: journey.leadId });
+
+    if (previousStage.friendlyName !== opportunityPayloadStage.friendlyName) {
+        thisLogger.info('Opportunity stage transitioned', { opportunityId, previousStage: previousStage, currentStage: opportunityPayloadStage });
+        await handleJourneyStageTransition(journey, 'opportunity', seekaProfileId, helper, thisLogger);
+    }
+    else {
+        thisLogger.debug('Opportunity stage did not transition', { opportunityId, currentStage: opportunityPayloadStage });
+    }
+}
+
+export const salesforceOpporunityToContentItem = (opportunity: SalesforceOpportunityWebhookPayloadObject): ContentItemActivityTrackingEventMetadata | undefined => {
+    const contentItem: ContentItemActivityTrackingEventMetadata = {};
+    let populated = false;
+
+    if (opportunity.Program_Full_Name__c) {
+        contentItem.contentName = opportunity.Program_Full_Name__c;
+        populated = true;
+    }
+    if (opportunity.SAEProgram__c) {
+        contentItem.identifiers = [opportunity.SAEProgram__c];
+        populated = true;
+    }
+    if (opportunity.Program_Discipline__c) {
+        contentItem.categoryName = opportunity.Program_Discipline__c;
+        populated = true;
+    }
+
+    if (populated) {
+        return contentItem;
+    }
+
+    return undefined;
+}
+
+const salesforceOpportunityToSeekaProfile = (opportunity: SalesforceOpportunityWebhookPayloadObject, whoId: string | null): PersonIdentifiers => {
+    const seekaProfile: PersonIdentifiers = {
+        // firstName: opportunity.FirstName ? [opportunity.FirstName] : [],
+        // lastName: opportunity.LastName ? [opportunity.LastName] : [],
+        email: opportunity.AccountEmail__c ? [opportunity.AccountEmail__c] : [],
+        phone: [],
+        // facebook: {
+        //     opportunity: opportunityPayload.opportunitySource?.toLowerCase() === 'facebook' && opportunityPayload.opportunity_Number__c ? [opportunityPayload.opportunity_Number__c] : []
+        // }
+    };
+    if (opportunity.SO_Account_Phone__c) {
+        seekaProfile.phone.push(opportunity.SO_Account_Phone__c);
+    }
+    if (opportunity.SO_Account_Mobile__c && opportunity.SO_Account_Mobile__c !== opportunity.SO_Account_Phone__c) {
+        seekaProfile.phone.push(opportunity.SO_Account_Mobile__c);
+    }
+    // const address: PlaceAddress = {};
+    // let hasAddress = false;
+    // if (opportunity.Country) {
+    //     address.country = opportunity.Country;
+    //     hasAddress = true;
+    // }
+    // if (opportunity.State) {
+    //     address.stateCode = opportunity.State;
+    //     hasAddress = true;
+    // }
+    // if (opportunity.PostalCode) {
+    //     address.postcode = opportunity.PostalCode;
+    //     hasAddress = true;
+    // }
+    // if (hasAddress) {
+    //     seekaProfile.address = [address];
+    // }
+
+    // Name parts
+    const nameParts = opportunity.Name ? opportunity.Name.split(' - ') : [];
+    if (nameParts.length > 2) {
+        const fullName = nameParts[0];
+        const names = separatePersonFullName(fullName);
+        if (names.firstName) {
+            seekaProfile.firstName = [names.firstName];
+        }
+        if (names.lastName) {
+            seekaProfile.lastName = [names.lastName];
+        }
+    }
+
+    // External ID
+    if (whoId) {
+        seekaProfile.eid = [whoId];
+    }
+
+    return seekaProfile;
+}

package/dist/ai-context/internal/examples/v2/navitas/app/server/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/ai-context/internal/examples/v2/navitas/app/server/src/lib/state/navitas/journey.ts

@@ -0,0 +1,165 @@
+import type { Logger } from 'winston';
+import { SalesforceEnrolmentFormWebhookPayloadObject } from './../../salesforce/models/index';
+
+import { queueNames, triggerBackgroundJob } from '../../jobs';
+import { SalesforceLeadStageLookup, SalesforceLeadWebhookPayloadObject, SalesforceOpportunityStageLookup, SalesforceOpportunityWebhookPayloadObject } from '../../salesforce/models';
+import { remove, set, tryGet } from '../redis';
+import { SeekaAppInstallState } from '../seeka/installations';
+import { hasBigQuerySettings, StateChangeQueuePayload } from './state/state-change';
+
+export interface NavitasJourneyState {
+    journeyId: string;
+    leadId?: string;
+    opportunityId?: string;
+    contactId?: string;
+    whoId?: string
+    leadPreviousStage?: SalesforceLeadStageLookup;
+    leadCurrentStage?: SalesforceLeadStageLookup;
+    opportunityPreviousStage?: SalesforceOpportunityStageLookup;
+    opportunityCurrentStage?: SalesforceOpportunityStageLookup;
+    lead?: SalesforceLeadWebhookPayloadObject;
+    opportunity?: SalesforceOpportunityWebhookPayloadObject;
+    seekaPersonId: string[];
+    leadLastTouched?: string;
+    opportunityLastTouched?: string;
+    lastTouched?: string;
+}
+
+const stateType = 'journey'
+const opportunityIdToLeadIdMappingStateType = 'leadToOpp';
+
+export const getJourneyIdFromLead = (lead: SalesforceLeadWebhookPayloadObject, logger: Logger): string | null => {
+    const journeyId = lead.Id || null;
+    if (!journeyId) {
+        logger.error('No journeyId found in lead', { lead });
+        throw new Error('No journeyId found in lead');
+    }
+
+    return 'sf:lead:' + journeyId;
+}
+
+export const getJourneyIdFromEnrolmentForm = (form: SalesforceEnrolmentFormWebhookPayloadObject, logger: Logger): string | null => {
+    const journeyId = form.Lead_ID__c || null;
+    if (!journeyId) {
+        logger.error('No journeyId found in form', { form });
+        // throw new Error('No journeyId found in lead');
+    }
+
+    return 'sf:lead:' + journeyId;
+}
+
+export const setOpportunityIdToLeadIdMapping = async (leadId: string, opportunityId: string, logger: Logger): Promise<void> => {
+    if (!leadId || !opportunityId) throw new Error('LeadId or OpportunityId is missing');
+
+    await set(opportunityIdToLeadIdMappingStateType, opportunityId, leadId);
+}
+
+export const getJourneyIdFromOpportunity = async (opportunity: SalesforceOpportunityWebhookPayloadObject, logger: Logger): Promise<string | null> => {
+    const leadId = await tryGet<string>(opportunityIdToLeadIdMappingStateType, opportunity.Id);
+    if (!leadId) {
+        return null;
+    }
+    else {
+        logger.debug('Found journeyId from opportunity mapped via lead ID', { opportunityId: opportunity.Id, leadId });
+    }
+
+    return 'sf:lead:' + leadId;
+}
+
+export const tryGetJourney = async (journeyId: string, throwWhenNotFound: boolean, logger: Logger): Promise<NavitasJourneyState | null> => {
+    const installation = await tryGet<NavitasJourneyState>(stateType, journeyId, 'json');
+    if (installation == null && throwWhenNotFound) {
+        throw new Error(`Journey ${journeyId} not found`);
+    }
+
+    return installation;
+}
+
+export const createOrUpdateJourney = async (state: NavitasJourneyState, leadTouched: boolean, opportunityTouched: boolean, logger: Logger): Promise<NavitasJourneyState> => {
+    const existingJourney = await tryGetJourney(state.journeyId, false, logger)
+    const creating = existingJourney === null;
+
+    const now = new Date().toISOString();
+    state.lastTouched = now;
+    if (leadTouched)
+        state.leadLastTouched = now;
+
+    if (opportunityTouched)
+        state.opportunityLastTouched = now;
+
+    // Distinct person Id
+    state.seekaPersonId = Array.from(new Set(state.seekaPersonId || []));
+
+    if (!creating) {
+        // Ensure not overwriting lead with older data
+        if (leadTouched) {
+            const previousLeadModified = existingJourney.lead?.SystemModstamp;
+            const currentLeadModified = state.lead?.SystemModstamp;
+            if (previousLeadModified && currentLeadModified) {
+                if (new Date(previousLeadModified) > new Date(currentLeadModified)) {
+                    logger.warn('Not updating journey lead state with older lead data', { journeyId: state.journeyId, previousLeadModified, currentLeadModified });
+                    state.lead = existingJourney.lead;
+                }
+            }
+        }
+
+        // Ensure not overwriting opportunity with older data
+        if (opportunityTouched) {
+            const previousOpportunityModified = existingJourney.opportunity?.SystemModstamp;
+            const currentOpportunityModified = state.opportunity?.SystemModstamp;
+            if (previousOpportunityModified && currentOpportunityModified) {
+                if (new Date(previousOpportunityModified) > new Date(currentOpportunityModified)) {
+                    logger.warn('Not updating journey lead state with older lead data', { journeyId: state.journeyId, previousOpportunityModified, currentOpportunityModified });
+                    state.opportunity = existingJourney.opportunity;
+                }
+            }
+        }
+    }
+
+    if (!state.opportunityId && state.leadId && state.lead && state.lead.ConvertedOpportunityId) {
+        state.opportunityId = state.lead.ConvertedOpportunityId;
+        await setOpportunityIdToLeadIdMapping(state.leadId, state.lead.ConvertedOpportunityId, logger);
+    }
+
+    await set(stateType, state.journeyId, state, 'json');
+
+    logger.info(creating ? 'Created journey state' : 'Updated journey state', { journeyId: state.journeyId });
+
+    return state;
+}
+
+export const deleteJourney = async (journeyId: string, logger: Logger): Promise<void> => {
+    await remove(stateType, journeyId);
+
+    logger.info('Deleted journey state', { journeyId });
+}
+
+const isContactMerged = (oldWhoId: string, newWhoId: string): boolean => {
+    if (oldWhoId && newWhoId && oldWhoId !== newWhoId) {
+        return true
+    }
+
+    return false
+}
+
+export const handleContactMerge = async (oldWhoId: string, newWhoId: string, whoId: string, sourceName: 'lead' | 'opportunity' | 'enrolmentform', sourceId: string, installation: SeekaAppInstallState, logger: Logger) => {
+    if (!hasBigQuerySettings(installation)) return;
+
+    const merged = isContactMerged(oldWhoId, newWhoId);
+    if (!merged) return
+
+    logger.info('Contact detected as merged', { oldWhoId, newWhoId, whoId, sourceName, sourceId })
+
+    await triggerBackgroundJob(queueNames.handleStateChange, {
+        payload: {
+            oldWhoId,
+            newWhoId,
+            whoId,
+            sourceId,
+            sourceName
+        } as StateChangeQueuePayload,
+        organisationBrandId: installation.organisationBrandId,
+        organisationId: installation.organisationId,
+        applicationInstallId: installation.applicationInstallId
+    }, logger)
+}

package/dist/ai-context/internal/examples/v2/navitas/app/server/src/lib/state/navitas/state/models.ts

@@ -0,0 +1,43 @@
+import bigquery from "@google-cloud/bigquery/build/src/types";
+
+export const externalIdLookupBigQuerySchema: bigquery.ITableSchema = {
+    fields: [
+        {
+            name: "timestamp",
+            type: "TIMESTAMP",
+            mode: "REQUIRED",
+            description: "The timestamp for when the record was either created or last updated."
+        },
+        {
+            name: "rowVersion",
+            type: "INT64",
+            mode: "REQUIRED",
+            description: "The version number of the row. Incremented by 1 for each update to the row."
+        },
+        {
+            name: "oldWhoId",
+            type: "STRING",
+            mode: "REQUIRED"
+        },
+        {
+            name: "newWhoId",
+            type: "STRING",
+            mode: "REQUIRED"
+        },
+        {
+            name: "whoId",
+            type: "STRING",
+            mode: "REQUIRED"
+        },
+        {
+            name: "sourceName",
+            type: "STRING",
+            mode: "REQUIRED"
+        },
+        {
+            name: "sourceId",
+            type: "STRING",
+            mode: "REQUIRED"
+        }
+    ]
+}

package/dist/ai-context/internal/examples/v2/navitas/app/server/src/lib/state/navitas/state/state-change.ts

@@ -0,0 +1,53 @@
+import { GoogleBigQuerySettings, migrateIfRequired, sendDataToGoogleBigQuery } from "@seeka-labs-internal/lib-google-bigquery";
+import { Logger } from "winston";
+import { BackgroundJobRequestContext } from "../../../jobs";
+import { createNewClient, getKey } from '../../redis';
+import { SeekaAppInstallState } from "../../seeka/installations";
+import { externalIdLookupBigQuerySchema } from './models';
+
+export interface StateChangeQueueItem extends BackgroundJobRequestContext<StateChangeQueuePayload> {
+
+}
+
+export interface StateChangeQueuePayload {
+    oldWhoId: string,
+    newWhoId: string,
+    whoId: string,
+    sourceName: 'lead' | 'opportunity' | 'enrolmentform',
+    sourceId: string
+}
+
+export const handleStateChange = async (payload: StateChangeQueueItem, installation: SeekaAppInstallState, logger: Logger) => {
+    logger.info('Handling state change', { payload })
+
+    // Migrate schema
+    const redis = createNewClient();
+    const settings = toBigQuerySettings(installation, "stream-lookup-whoid");
+    await migrateIfRequired(settings, externalIdLookupBigQuerySchema, null, redis, (t, k) => getKey(t, k), logger);
+
+    await sendDataToGoogleBigQuery(logger, settings, [
+        {
+            timestamp: new Date(),
+            rowVersion: 1,
+            ...payload.payload
+        }
+    ])
+}
+
+export const hasBigQuerySettings = (install: SeekaAppInstallState): boolean => {
+    if (!install.installationSettings.bigQueryDatasetId || !install.installationSettings.googleProjectId || !install.installationSettings.googleServiceAccountJson) return false;
+
+    return true
+}
+
+export const toBigQuerySettings = (install: SeekaAppInstallState, tableName: string): GoogleBigQuerySettings | null => {
+    if (!hasBigQuerySettings(install)) return null;
+
+    // TODO
+    return {
+        datasetId: install.installationSettings.bigQueryDatasetId,
+        tableName,
+        googleServiceAccountJson: install.installationSettings.googleServiceAccountJson,
+        googleProjectId: install.installationSettings.googleProjectId
+    }
+}

package/dist/ai-context/internal/examples/v2/navitas/app/server/src/lib/state/redis/index.ts

@@ -0,0 +1,102 @@
+import { createClient, RedisClientType } from 'redis';
+
+import winston from 'winston';
+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}`;
+
+export const createNewClient = (): RedisClientType => {
+    const c = createClient({
+        url: redisConn,
+        disableClientInfo: true,
+
+    })
+        .on('error', (err) => logger.error('Redis Client ', { ex: winston.exceptions.getAllInfo(err) }));
+
+    return c as RedisClientType
+}
+
+const redisClient = createNewClient()
+
+export const connect = async () => {
+    await redisClient.connect();
+}
+
+export const isConnected = () => {
+    return redisClient.isOpen;
+}
+
+export const disconnect = async () => {
+    await redisClient.destroy();
+}
+
+const getKeyPrefix = (stateType: string) => `seeka:app:${process.env.SEEKA_APP_ID}:${stateType}`
+export const getKey = (stateType: string, key: string) => `${getKeyPrefix(stateType)}:${key}`
+
+export async function getOrCreate<TState>(stateType: string, key: string, toCreate: TState, mode: 'string' | 'json' = 'string'): Promise<TState> {
+    const fullKey = getKey(stateType, key);
+    const existingStr = await getString(redisClient, fullKey);
+    if (existingStr) return JSON.parse(existingStr);
+
+    if (mode === 'json') {
+        await redisClient.json.set(fullKey, '$', toCreate as never);
+    }
+    else {
+        await redisClient.set(fullKey, JSON.stringify(toCreate));
+    }
+
+    return toCreate;
+}
+
+export async function tryGet<TState>(stateType: string, key: string, mode: 'string' | 'json' = 'string'): Promise<TState | null> {
+    const fullKey = getKey(stateType, key);
+
+    if (mode === 'json') {
+        const existing = await redisClient.json.get(fullKey);
+        if (existing) return existing as TState;
+    }
+    else {
+        const existingStr = await getString(redisClient, 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, mode: 'string' | 'json' = 'string'): Promise<void> {
+    const fullKey = getKey(stateType, key);
+
+    if (mode === 'json') {
+        await redisClient.json.set(fullKey, '$', toCreate as never);
+    }
+    else {
+        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);
+}
+
+async function getString(redisClient: any, key: string): Promise<string> {
+    const result = await redisClient.get(key);
+    if (typeof result === 'string') {
+        return result;
+    }
+    if (result) {
+        return result.toString();
+    }
+    return '';
+}

package/dist/ai-context/internal/examples/v2/navitas/app/server/src/lib/state/seeka/installations.ts

@@ -0,0 +1,66 @@
+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: NavitasAppInstallSettings
+    // State relating to the app and installation of the app
+    installationState: NavitasAppInstallState;
+
+    // When the app was installed
+    installedAt: string; // new Date().toISOString()
+}
+
+export interface NavitasAppInstallState {
+    grantedPermissions?: string[]
+}
+
+export type NavitasAppInstallSettings = {
+    bigQueryDatasetId?: string | undefined;
+    googleProjectId?: string | undefined;
+    googleServiceAccountJson?: string | 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 });
+}