@seeka-labs/cli-apps 3.7.0 → 3.8.2

package/dist/ai-context/internal/examples/v1/me-and-u-manage/src/functions/seekaAppWebhook.ts

@@ -0,0 +1,216 @@
+import { app, HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';
+import {
+    SeekaAppInstalledWebhookPayload,
+    SeekaAppInstallSettingsUpdatedWebhookPayload, SeekaAppUninstalledWebhookPayload,
+    SeekaWebhookCallType, SeekaWebhookPayload,
+    throwOnInvalidWebhookSignature
+} from '@seeka-labs/sdk-apps-server';
+
+import { queueNames, triggerBackgroundJob } from '../lib/jobs';
+import { webhookLogger } from '../lib/logging';
+import { startServices } from '../lib/services';
+import {
+    createOrUpdateInstallation, deleteInstallation, MeAndUManageInstallSettings, SeekaAppInstallState, tryGetInstallation
+} from '../lib/state/seeka/installations';
+
+import type { Logger } from 'winston';
+import winston from 'winston';
+import { validateApiConnection } from '../lib/me-and-u';
+import { findMeAndUMenuBySlug } from '../lib/me-and-u/menus';
+
+app.http('seekaAppWebhook', {
+    methods: ['POST'],
+    authLevel: 'anonymous',
+    route: 'webhook/seeka/app',
+    handler: seekaAppWebhook
+});
+
+export async function seekaAppWebhook(req: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
+    const bodyStr = (await req.text()) as string;
+    const body = JSON.parse(bodyStr) as SeekaWebhookPayload;
+
+    const logger = webhookLogger(body, context);
+    logger.profile('http.seeka.webhook.app')
+    logger.verbose('Received webhook from Seeka', { body });
+
+    // Handle probe
+    if (body.type === SeekaWebhookCallType.Probe) {
+        return {
+            status: 204
+        }
+    }
+
+    // Validate webhook
+    try {
+        throwOnInvalidWebhookSignature(process.env.SEEKA_APP_SECRET as string, req.headers, bodyStr);
+        logger.debug('Webhook signature validated', { body });
+    }
+    catch {
+        logger.warn('Webhook signature invalid', { body });
+        return {
+            status: 401,
+            jsonBody: { error: "Webhook call invalid" }
+        }
+    }
+
+    if (body.isTest) {
+        // This is a test webhook call
+        return {
+            status: 204
+        }
+    }
+
+    await startServices(logger);
+
+    // Check if the webhook is for an app we have installed
+    let installation: SeekaAppInstallState | null = null;
+    if (body.type != SeekaWebhookCallType.AppInstalled) {
+        installation = await tryGetInstallation((body as SeekaAppInstalledWebhookPayload).context?.applicationInstallId as string, false, logger);
+        if (installation == null) {
+            logger.warn('Webhook call cannot be processed as the installation ID is not known by this app', { body });
+
+            return {
+                status: 422,
+                jsonBody: { error: "App not installed" }
+            }
+        }
+    }
+
+    // Do something
+    let errorMessage: string | null = null;
+    try {
+        switch (body.type) {
+            case SeekaWebhookCallType.AppInstalled:
+                {
+                    errorMessage = await onInstallation(body as SeekaAppInstalledWebhookPayload, logger);
+                    break;
+                }
+            case SeekaWebhookCallType.AppInstallSettingsUpdated:
+                {
+                    errorMessage = await onInstallationSettingsUpdate(body as SeekaAppInstallSettingsUpdatedWebhookPayload, logger);
+                    break;
+                }
+            case SeekaWebhookCallType.AppUninstalled:
+                {
+                    if (!body.isTest) {
+                        const payload = body as SeekaAppUninstalledWebhookPayload;
+                        await deleteInstallation(payload.context?.applicationInstallId as string, logger)
+                    }
+                    break;
+                }
+            case SeekaWebhookCallType.ActivityAccepted:
+                {
+                    // no-op
+                    break;
+                }
+            case SeekaWebhookCallType.IdentityChanged:
+                {
+                    // no-op
+                    break;
+                }
+        }
+    }
+    catch (err) {
+        logger.error('Failed to handle webhook', { ex: winston.exceptions.getAllInfo(err) });
+        return {
+            status: 500,
+            jsonBody: { error: "Request failed" }
+        }
+    }
+    finally {
+        logger.profile('http.seeka.webhook.app')
+        logger.verbose('Seeka webhook handled');
+    }
+
+    if (errorMessage) {
+        logger.warn('Webhook call failed', { errorMessage });
+        return {
+            status: 400,
+            jsonBody: { error: { message: errorMessage } }
+        }
+    }
+
+    return {
+        status: 204
+    }
+}
+
+const validateInstallationSettings = async (installSettings: MeAndUManageInstallSettings, logger: Logger): Promise<string | null> => {
+    // Returning an error message string here will block the installation request or settings update request by the user installing the app
+    if (!installSettings.connection?.meAndUAccessToken) return 'MeAndU access token is required';
+
+    if (!installSettings.connection?.meAndUVenueSlug) return 'MeAndU venue slug is required';
+
+    const errorMessage = await validateApiConnection(installSettings, logger);
+    if (errorMessage) return errorMessage;
+}
+
+const trySetMenuIdStateFromVenueSlug = async (installation: SeekaAppInstallState, venueSlug: string, logger: Logger): Promise<string | null> => {
+    const info = await findMeAndUMenuBySlug(installation.installationSettings, venueSlug, logger);
+    if (!info.errorMessage) {
+        installation.installationState.meAndUMenuId = info.menu.id;
+        return null;
+    }
+    else {
+        return info.errorMessage;
+    }
+}
+
+const onInstallation = async (payload: SeekaAppInstalledWebhookPayload, logger: Logger): Promise<string | null> => {
+    if (payload.isTest) return;
+
+    let errorMessage = await validateInstallationSettings(payload.content?.installationSettings || {}, logger);
+    if (errorMessage) return errorMessage;
+
+    const newInstallState: SeekaAppInstallState = {
+        ...payload.context,
+        applicationInstallId: payload.context?.applicationInstallId as string,
+        organisationBrandId: payload.context?.organisationBrandId as string,
+        organisationId: payload.context?.organisationId as string,
+        installationState: {
+            grantedPermissions: payload.content?.grantedPermissions || []
+        },
+        installedAt: new Date().toISOString(),
+        installationSettings: payload.content?.installationSettings || {}
+    };
+
+    errorMessage = await trySetMenuIdStateFromVenueSlug(newInstallState, payload.content?.installationSettings?.connection?.meAndUVenueSlug as string, logger);
+    if (errorMessage) return errorMessage;
+
+    await createOrUpdateInstallation(newInstallState, logger)
+
+    await triggerBackgroundJob(queueNames.processNewMeAndUOrdersQueueName, {
+        ...payload.context,
+        causationId: payload.causationId,
+        correlationId: payload.requestId
+    }, logger)
+}
+
+const onInstallationSettingsUpdate = async (payload: SeekaAppInstallSettingsUpdatedWebhookPayload, logger: Logger): Promise<string | null> => {
+    if (payload.isTest) return;
+
+    let errorMessage = await validateInstallationSettings(payload.content?.installationSettings || {}, logger);
+    if (errorMessage) return errorMessage;
+
+    const existingInstallation = await tryGetInstallation(payload.context?.applicationInstallId as string, true, logger) as SeekaAppInstallState;
+
+    const newInstallState: SeekaAppInstallState = {
+        ...existingInstallation,
+        installationState: {
+            ...existingInstallation.installationState,
+            grantedPermissions: payload.content?.grantedPermissions || []
+        },
+        installationSettings: payload.content?.installationSettings || {},
+    }
+    errorMessage = await trySetMenuIdStateFromVenueSlug(newInstallState, payload.content?.installationSettings?.connection?.meAndUVenueSlug as string, logger);
+    if (errorMessage) return errorMessage;
+
+    await createOrUpdateInstallation(newInstallState, logger)
+
+    // TODO: Remove below trigger
+    // await triggerBackgroundJob(queueNames.processNewMeAndUOrdersQueueName, {
+    //     ...payload.context,
+    //     causationId: payload.causationId,
+    //     correlationId: payload.requestId
+    // }, logger)
+}

package/dist/ai-context/internal/examples/v1/me-and-u-manage/src/lib/jobs/index.ts

@@ -0,0 +1,97 @@
+import { QueueClient } from '@azure/storage-queue';
+import { isArray } from 'lodash';
+import type { Logger } from 'winston';
+import winston from 'winston';
+
+export interface BackgroundJobRequestContext {
+    organisationId?: string;
+    organisationBrandId?: string;
+    applicationInstallId?: string;
+    causationId: string
+    correlationId: string
+}
+
+export const signatureHeaderName = 'x-signature-hmac';
+export const apiKeyHeaderName = 'x-api-key';
+
+export const jobNames = {
+    pollForNewMeAndUData: 'poll-new-meandu-data',
+}
+
+export const queueNames = {
+    processNewMeAndUOrdersQueueName: 'process-new-meandu-orders-queue',
+    processNewMeAndUMarketingOptInsQueueName: 'process-new-meandu-marketingoptin-queue'
+}
+
+export const triggerBackgroundJob = async (queueName: string, context: BackgroundJobRequestContext, logger: Logger): Promise<void> => {
+    const queueClient = new QueueClient(process.env.AzureWebJobsStorage as string, queueName);
+    return triggerBackgroundJobWithQueue(queueClient, context, logger);
+}
+
+const serialiseQueuePayload = (payload: unknown): string => {
+    const jsonString = JSON.stringify(payload)
+    return Buffer.from(jsonString).toString('base64')
+}
+
+export const deserialiseQueuePayload = <TPayload>(queueItem: any, logger: Logger): TPayload[] => {
+    try {
+        if (typeof queueItem !== 'string') {
+            if (isArray(queueItem)) {
+                return queueItem
+            }
+            return [queueItem]
+        }
+        else {
+            const jsonString = Buffer.from(queueItem, 'base64').toString()
+            const parsed = JSON.parse(jsonString);
+
+            if (isArray(parsed)) {
+                return parsed
+            }
+            return [parsed]
+        }
+    }
+    catch (err) {
+        logger.error('Failed to deserialise queue payload', { ex: winston.exceptions.getAllInfo(err), queueItem });
+        throw new Error(`Failed to deserialise queue payload`);
+    }
+}
+
+export const triggerBackgroundJobWithQueue = async (queueClient: QueueClient, context: BackgroundJobRequestContext, logger: Logger): Promise<void> => {
+    const body = {
+        ...context
+    }
+    const bodyStr = serialiseQueuePayload(body);
+
+    const response = await queueClient.sendMessage(bodyStr, { messageTimeToLive: -1 });
+
+    if (response.errorCode) {
+        const { requestId, date, errorCode } = response;
+        logger.error("Failed to trigger background job", { body, requestId, date, errorCode })
+        throw new Error(`Failed to trigger background job: ${response.errorCode}`);
+    }
+    else {
+        logger.debug("Background job triggered", { body, messageId: response.messageId, context })
+    }
+}
+
+export const sendQueueMessageToPoisonQueue = async (queueName: string, context: BackgroundJobRequestContext, logger: Logger): Promise<void> => {
+    const body = {
+        ...context
+    }
+    const bodyStr = serialiseQueuePayload(body);
+
+    // https://learn.microsoft.com/en-us/azure/azure-functions/functions-bindings-storage-queue-trigger?tabs=python-v2%2Cisolated-process%2Cnodejs-v4%2Cextensionv5&pivots=programming-language-typescript#poison-messages
+    const queueClient = new QueueClient(process.env.AzureWebJobsStorage as string, `${queueName}-poison`);
+
+    const response = await queueClient.sendMessage(bodyStr, { messageTimeToLive: -1 });
+
+    if (response.errorCode) {
+        const { requestId, date, errorCode } = response;
+        logger.error("Failed to push to poison queue", { body, requestId, date, errorCode })
+        throw new Error(`Failed to push to poison queue: ${response.errorCode}`);
+    }
+    else {
+        logger.verbose("Message pushed to poison queue", { body, messageId: response.messageId, context })
+    }
+}

package/dist/ai-context/internal/examples/v1/me-and-u-manage/src/lib/logging/index.ts

@@ -0,0 +1,93 @@
+import * as winston from 'winston';
+
+import { InvocationContext } from '@azure/functions';
+import { SeqTransport } from '@datalust/winston-seq';
+
+import * as packageJson from '../../../package.json';
+import { BackgroundJobRequestContext } from '../jobs';
+
+import type {
+    SeekaWebhookPayload, SeekaWebhookPayloadOfSeekaAppWebhookContext
+} from '@seeka-labs/sdk-apps-server';
+
+const loggerTransports: winston.transport[] = [
+    new winston.transports.Console({
+        level: process.env.LOGGING_LEVEL,
+        format: winston.format.combine(
+            winston.format.errors({ stack: true }),
+            winston.format.cli(),
+            winston.format.splat(),
+        ),
+        handleExceptions: true,
+        handleRejections: true,
+    }),
+]
+if (process.env.LOGGING_SEQ_SERVERURL) {
+    loggerTransports.push(
+        new SeqTransport({
+            level: process.env.LOGGING_LEVEL,
+            serverUrl: process.env.LOGGING_SEQ_SERVERURL,
+            apiKey: process.env.LOGGING_SEQ_APIKEY,
+            onError: ((e) => { console.error('Failed to configure Seq logging transport', e) }),
+            format: winston.format.combine(
+                winston.format.errors({ stack: true }),
+                winston.format.json(),
+            ),
+            handleExceptions: true,
+            handleRejections: true,
+        })
+    )
+}
+
+export const logger = winston.createLogger({
+    level: process.env.LOGGING_LEVEL,
+    defaultMeta: {
+        seekaAppId: process.env.SEEKA_APP_ID,
+        Hosting_Provider: 'azure',
+        Release_Version: `v${packageJson.version}`,
+        Hosting_Region: process.env.REGION_NAME,
+        Service_Instance_Id: process.env.WEBSITE_ROLE_INSTANCE_ID,
+        AzureFunctions_FunctionName: process.env.WEBSITE_SITE_NAME,
+        Service: `app/${packageJson.name}`,
+    },
+    transports: loggerTransports,
+    exitOnError: false,
+});
+
+export const childLogger = (meta: object) => logger.child(meta);
+
+export const webhookLogger = (payload: SeekaWebhookPayload, functionContext: InvocationContext) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const meta: any = {
+        seekaWebhookType: payload.type,
+        seekaWebhookIsTest: payload.isTest,
+        RequestId: payload.requestId,
+        AzureFunctions_InvocationId: functionContext.invocationId,
+        CausationId: payload.causationId,
+        CorrelationId: payload.causationId,
+    }
+
+    const context = (payload as SeekaWebhookPayloadOfSeekaAppWebhookContext).context;
+    if (context) {
+        meta.seekaAppInstallId = context.applicationInstallId;
+        meta.seekaAppInstallOrganisationBrandId = context.organisationBrandId;
+        meta.seekaAppInstallOrganisationId = context.organisationId;
+    }
+
+    return childLogger(meta)
+}
+
+export const backgroundJobLogger = (jobName: string, jobContext: BackgroundJobRequestContext | undefined, functionContext: InvocationContext) => {
+    const meta: object = {
+        jobContext,
+        jobName,
+        AzureFunctions_InvocationId: functionContext.invocationId,
+        CausationId: jobContext?.causationId,
+        CorrelationId: jobContext?.causationId,
+        seekaAppInstallId: jobContext?.applicationInstallId,
+        seekaAppInstallOrganisationBrandId: jobContext?.organisationBrandId,
+        seekaAppInstallOrganisationId: jobContext?.organisationId
+    }
+
+    return childLogger(meta)
+}

package/dist/ai-context/internal/examples/v1/me-and-u-manage/src/lib/me-and-u/consent/index.ts

@@ -0,0 +1,196 @@
+import winston, { Logger } from "winston";
+import { MeAndUManageInstallSettings, SeekaAppInstallState, createOrUpdateInstallation } from "../../state/seeka/installations";
+import { MeAndUGuest, makeMeAndUGraphQlRequest, meAndUGuestToSeekaPerson } from "..";
+import { PersonIdentifiers, PrivacyConsentType, SeekaAppHelper, TrackingEventSourceOriginType } from "@seeka-labs/sdk-apps-server";
+import * as packageJson from '../../../../package.json';
+
+type GetMeAndUMarketingOptInsVariables = {
+    first?: number;
+    after?: string;
+    sort?: {
+        sortKey: "CREATED_AT" | string
+        direction: "ASC" | "DESC"
+    };
+    filter?: {
+        optedInAt: {
+            gt?: string; // Format "2024-02-20T05:30:05.464Z"
+        },
+        menu: {
+            equals: string
+        }
+    };
+}
+
+export const handleMeAndUMarketingOptInPage = async (installation: SeekaAppInstallState, page: { marketingOptIns: MeAndUMarketingOptIn[], lastCursor: string, lastCreationDate: string }, logger: Logger): Promise<void> => {
+    logger.debug('Processing MeAndU marketingoptin page', { installationId: installation.applicationInstallId, count: page.marketingOptIns.length });
+
+    // Transform marketingoptins to Seeka profiles
+    const seekaIdentities = page.marketingOptIns.map(e => meAndUMarketingConsentToSeekaProfile(e, installation, logger)).filter(e => Boolean(e));
+
+    // Fire off Seeka profiles
+    if (seekaIdentities.length > 0) {
+        logger.verbose('Firing off Seeka identity consent', { installationId: installation.applicationInstallId, count: seekaIdentities.length });
+        await fireSeekaIdentities(installation, seekaIdentities, logger);
+    }
+    else {
+        logger.verbose('No Seeka identity consent to fire', { installationId: installation.applicationInstallId });
+    }
+
+    // Update state
+    await createOrUpdateInstallation({
+        ...installation,
+        installationState: {
+            ...installation.installationState,
+            marketingOptInsRetrievedUpToCreationDate: page.lastCreationDate ? page.lastCreationDate : installation.installationState.marketingOptInsRetrievedUpToCreationDate
+        }
+    }, logger);
+}
+
+const fireSeekaIdentities = async (installation: SeekaAppInstallState, batch: PersonIdentifiers[], logger: Logger): Promise<void> => {
+    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: packageJson.name, version: packageJson.version }, installation.installationState.grantedPermissions, logger);
+
+    await helper.api.mergeIdentityBatch(batch, {
+        origin: TrackingEventSourceOriginType.PhysicalStore,
+    })
+}
+
+const meAndUMarketingConsentToSeekaProfile = (marketingOptIn: MeAndUMarketingOptIn, installation: SeekaAppInstallState, logger: Logger): PersonIdentifiers | null => {
+    if (marketingOptIn.marketableGuest == null) {
+        logger.warning('MarketingOptIn does not have a marketableGuest', { marketingOptInId: marketingOptIn.id });
+        return null;
+    }
+
+    const dateOptInStr = marketingOptIn.updatedAt || marketingOptIn.createdAt;
+    if (!dateOptInStr) {
+        logger.warning('MarketingOptIn does not have an updatedAt or createdAt, setting to now', { marketingOptInId: marketingOptIn.id });
+    }
+    const consentInfo = {
+        type: PrivacyConsentType.Explicit,
+        consentGrantedAt: dateOptInStr ? new Date(dateOptInStr) : new Date(),
+        consentGrantedSourceName: 'Me&u'
+    };
+
+    const identity = meAndUGuestToSeekaPerson(marketingOptIn.marketableGuest);
+    identity.consent = {
+        marketing: {
+            email: {
+                ...consentInfo
+            },
+            sms: {
+                ...consentInfo
+            }
+        }
+    }
+
+    return identity;
+}
+
+export const getMeAndUMarketingOptIns = async (installationSettings: MeAndUManageInstallSettings, variables: GetMeAndUMarketingOptInsVariables, logger: Logger): Promise<MeAndUMarketingOptInsResponse | null> => {
+    try {
+        const response = await makeMeAndUGraphQlRequest<MeAndUMarketingOptInsResponse>(
+            installationSettings,
+            `query marketingOptIns ($first: Int, $after: String, $sort: MarketingOptInSortArgs, $filter: MarketingOptInFilter) {
+                    marketingOptIns (first: $first, after: $after, sort: $sort, filter: $filter) {
+                        edges {
+                            node {
+                                createdAt
+                                updatedAt
+                                message
+                                marketableGuest {
+                                    email
+                                    mobile
+                                    name
+                                }
+                            }
+                        }
+                        pageInfo {
+                            endCursor
+                            hasNextPage
+                        }
+                    }
+                }`,
+            variables
+        );
+
+        if (response.errors) {
+            logger.error('Error fetching MeAndU MarketingOptIns', { errors: response.errors });
+            return null;
+        }
+
+        return response.data;
+    }
+    catch (err) {
+        // TODO: Add error handling
+        logger.error('Error making request to fetch MeAndU MarketingOptIns', { ex: winston.exceptions.getAllInfo(err) });
+        return null
+    }
+}
+
+export const getAllMeAndUMarketingOptIns = async (installation: SeekaAppInstallState, handlePage: (page: { marketingOptIns: MeAndUMarketingOptIn[], lastCursor: string, lastCreationDate: string }) => Promise<void>, logger: Logger): Promise<void> => {
+    // Small page size to work within query cost limits - https://stable-api-docs.mryum.com/docs/overview/usage
+    const pageSize = 25;
+    let cursor: string | null = null
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const response = await getMeAndUMarketingOptIns(installation.installationSettings, {
+            first: pageSize,
+            after: cursor,
+            sort: {
+                sortKey: "CREATED_AT",
+                direction: "ASC"
+            },
+            filter: {
+                optedInAt: {
+                    gt: installation.installationState.marketingOptInsRetrievedUpToCreationDate || installation.installedAt
+                },
+                menu: {
+                    equals: installation.installationState.meAndUMenuId
+                }
+            }
+        }, logger);
+        if (response != null) {
+            if (response.marketingOptIns.edges.length === 0) {
+                break;
+            }
+            await handlePage({
+                marketingOptIns: [...response.marketingOptIns.edges.map(edge => edge.node)],
+                lastCursor: response.marketingOptIns.pageInfo.endCursor,
+                lastCreationDate: response.marketingOptIns.edges[response.marketingOptIns.edges.length - 1].node.createdAt
+            })
+
+            cursor = response.marketingOptIns.pageInfo.endCursor;
+            if (!response.marketingOptIns.pageInfo.hasNextPage) {
+                break;
+            }
+        }
+        else {
+            // Errored
+            logger.error('Error fetching all MeAndU MarketingOptIns - response was null');
+            break;
+        }
+    }
+}
+
+export interface MeAndUMarketingOptInsResponse {
+    marketingOptIns: {
+        edges: {
+            node: MeAndUMarketingOptIn
+        }[]
+        pageInfo: {
+            endCursor: string;
+            hasNextPage: boolean;
+        }
+    }
+}
+
+export interface MeAndUMarketingOptIn {
+    createdAt: string;
+    updatedAt?: string;
+    message: string;
+    marketableGuest: MeAndUGuest;
+    id: string;
+}