@allma/core-sdk 1.0.1

package/dist/apiResponseBuilder.d.ts

@@ -0,0 +1,26 @@
+import type { AdminApiErrorResponse, AdminApiSuccessResponse } from '@allma/core-types';
+import type { APIGatewayProxyResultV2 } from 'aws-lambda';
+/**
+ * Builds a standardized success response object.
+ * @param data The data payload for the successful response.
+ * @returns AdminApiSuccessResponse<T>
+ */
+export declare function buildSuccessResponse<T>(data: T): AdminApiSuccessResponse<T>;
+/**
+ * Builds a standardized error response object.
+ * @param message The error message.
+ * @param code An optional error code (e.g., 'NOT_FOUND', 'VALIDATION_ERROR').
+ * @param details Optional additional error details.
+ * @returns AdminApiErrorResponse
+ */
+export declare function buildErrorResponse(message: string, code: string, details?: any): AdminApiErrorResponse;
+/**
+ * Creates a complete APIGatewayProxyResultV2 object for Lambda responses.
+ * It determines the HTTP status code based on the success flag and error code.
+ * @param defaultStatusCode The HTTP status code to use if success is true, or if no specific error code maps to a status.
+ * @param bodyObject The AdminApiSuccessResponse or AdminApiErrorResponse to be stringified in the body.
+ * @param correlationId Optional correlation ID for logging.
+ * @returns APIGatewayProxyResultV2
+ */
+export declare function createApiGatewayResponse(defaultStatusCode: number, bodyObject: AdminApiSuccessResponse<any> | AdminApiErrorResponse, correlationId?: string): APIGatewayProxyResultV2;
+//# sourceMappingURL=apiResponseBuilder.d.ts.map

package/dist/apiResponseBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiResponseBuilder.d.ts","sourceRoot":"","sources":["../src/apiResponseBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACxF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAG1D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAE3E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAC9B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,GAAG,GACd,qBAAqB,CAEvB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACpC,iBAAiB,EAAE,MAAM,EACzB,UAAU,EAAE,uBAAuB,CAAC,GAAG,CAAC,GAAG,qBAAqB,EAChE,aAAa,CAAC,EAAE,MAAM,GACvB,uBAAuB,CA8CzB"}

package/dist/apiResponseBuilder.js

@@ -0,0 +1,78 @@
+import { log_debug } from './logger.js';
+/**
+ * Builds a standardized success response object.
+ * @param data The data payload for the successful response.
+ * @returns AdminApiSuccessResponse<T>
+ */
+export function buildSuccessResponse(data) {
+    return { success: true, data };
+}
+/**
+ * Builds a standardized error response object.
+ * @param message The error message.
+ * @param code An optional error code (e.g., 'NOT_FOUND', 'VALIDATION_ERROR').
+ * @param details Optional additional error details.
+ * @returns AdminApiErrorResponse
+ */
+export function buildErrorResponse(message, code, details) {
+    return { success: false, error: { message, code, details } };
+}
+/**
+ * Creates a complete APIGatewayProxyResultV2 object for Lambda responses.
+ * It determines the HTTP status code based on the success flag and error code.
+ * @param defaultStatusCode The HTTP status code to use if success is true, or if no specific error code maps to a status.
+ * @param bodyObject The AdminApiSuccessResponse or AdminApiErrorResponse to be stringified in the body.
+ * @param correlationId Optional correlation ID for logging.
+ * @returns APIGatewayProxyResultV2
+ */
+export function createApiGatewayResponse(defaultStatusCode, bodyObject, correlationId) {
+    let effectiveStatusCode = defaultStatusCode;
+    if (!bodyObject.success) {
+        const errorCode = bodyObject.error.code;
+        if (errorCode === 'NOT_FOUND') {
+            effectiveStatusCode = 404;
+        }
+        else if (errorCode === 'VALIDATION_ERROR' || errorCode === 'INVALID_INPUT') {
+            effectiveStatusCode = 400;
+        }
+        else if (errorCode === 'UNAUTHORIZED') {
+            effectiveStatusCode = 401;
+        }
+        else if (errorCode === 'FORBIDDEN') {
+            effectiveStatusCode = 403;
+        }
+        else if (errorCode === 'CONFLICT') {
+            effectiveStatusCode = 409;
+        }
+        else {
+            effectiveStatusCode = defaultStatusCode >= 400 ? defaultStatusCode : 500; // Default to 500 for errors if not specified
+        }
+    }
+    else if (defaultStatusCode === 204 && bodyObject.data === null) { // Handle 204 No Content specifically
+        // For 204, body should be empty.
+        log_debug(`Responding with statusCode: ${effectiveStatusCode} (No Content)`, {}, correlationId);
+        return {
+            statusCode: effectiveStatusCode,
+            headers: {
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Credentials': 'true',
+                'Access-Control-Allow-Headers': 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token',
+                'Access-Control-Allow-Methods': 'OPTIONS,GET,POST,PUT,DELETE,PATCH',
+            },
+            body: '', // Empty body for 204
+        };
+    }
+    log_debug(`Responding with statusCode: ${effectiveStatusCode}`, { bodyPreview: JSON.stringify(bodyObject).substring(0, 2000) }, correlationId);
+    return {
+        statusCode: effectiveStatusCode,
+        headers: {
+            'Content-Type': 'application/json',
+            'Access-Control-Allow-Origin': '*',
+            'Access-Control-Allow-Credentials': 'true',
+            'Access-Control-Allow-Headers': 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token',
+            'Access-Control-Allow-Methods': 'OPTIONS,GET,POST,PUT,DELETE,PATCH',
+        },
+        body: JSON.stringify(bodyObject),
+    };
+}
+//# sourceMappingURL=apiResponseBuilder.js.map

package/dist/apiResponseBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiResponseBuilder.js","sourceRoot":"","sources":["../src/apiResponseBuilder.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAI,IAAO;IAC3C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAC9B,OAAe,EACf,IAAY,EACZ,OAAa;IAEb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;AACjE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CACpC,iBAAyB,EACzB,UAAgE,EAChE,aAAsB;IAEtB,IAAI,mBAAmB,GAAG,iBAAiB,CAAC;IAE5C,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;QACtB,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;QACxC,IAAI,SAAS,KAAK,WAAW,EAAE,CAAC;YAC5B,mBAAmB,GAAG,GAAG,CAAC;QAC9B,CAAC;aAAM,IAAI,SAAS,KAAK,kBAAkB,IAAI,SAAS,KAAK,eAAe,EAAE,CAAC;YAC3E,mBAAmB,GAAG,GAAG,CAAC;QAC9B,CAAC;aAAM,IAAI,SAAS,KAAK,cAAc,EAAE,CAAC;YACtC,mBAAmB,GAAG,GAAG,CAAC;QAC9B,CAAC;aAAM,IAAI,SAAS,KAAK,WAAW,EAAE,CAAC;YACnC,mBAAmB,GAAG,GAAG,CAAC;QAC9B,CAAC;aAAM,IAAI,SAAS,KAAK,UAAU,EAAE,CAAC;YAClC,mBAAmB,GAAG,GAAG,CAAC;QAC9B,CAAC;aAAM,CAAC;YACJ,mBAAmB,GAAG,iBAAiB,IAAI,GAAG,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,6CAA6C;QAC3H,CAAC;IACL,CAAC;SAAM,IAAI,iBAAiB,KAAK,GAAG,IAAI,UAAU,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC,CAAC,qCAAqC;QACvG,iCAAiC;QACjC,SAAS,CAAC,+BAA+B,mBAAmB,eAAe,EAAE,EAAE,EAAE,aAAa,CAAC,CAAC;QAChG,OAAO;YACL,UAAU,EAAE,mBAAmB;YAC/B,OAAO,EAAE;gBACL,6BAA6B,EAAE,GAAG;gBAClC,kCAAkC,EAAE,MAAM;gBAC1C,8BAA8B,EAAE,sEAAsE;gBACtG,8BAA8B,EAAE,mCAAmC;aACtE;YACD,IAAI,EAAE,EAAE,EAAE,qBAAqB;SAChC,CAAC;IACJ,CAAC;IAGD,SAAS,CAAC,+BAA+B,mBAAmB,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,aAAa,CAAC,CAAC;IAC/I,OAAO;QACH,UAAU,EAAE,mBAAmB;QAC/B,OAAO,EAAE;YACL,cAAc,EAAE,kBAAkB;YAClC,6BAA6B,EAAE,GAAG;YAClC,kCAAkC,EAAE,MAAM;YAC1C,8BAA8B,EAAE,sEAAsE;YACtG,8BAA8B,EAAE,mCAAmC;SACtE;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;KACnC,CAAC;AACN,CAAC"}

package/dist/authUtils.d.ts

@@ -0,0 +1,55 @@
+import type { APIGatewayProxyEventV2WithJWTAuthorizer } from 'aws-lambda';
+import { AdminPermission, AdminRole } from '@allma/core-types';
+export declare const ADMIN_COGNITO_GROUP_NAME = "Admins";
+export declare const CUSTOM_ADMIN_ROLES_ATTRIBUTE = "custom:admin_roles";
+export interface AuthContext {
+    userId: string;
+    username: string;
+    cognitoGroups: string[];
+    adminPermissions: {
+        roles: AdminRole[];
+        permissions: AdminPermission[];
+    };
+    isAuthenticated: boolean;
+    isSuperAdmin: boolean;
+    hasPermission: (permission: AdminPermission) => boolean;
+}
+/**
+ * Options for configuring authentication behavior.
+ */
+export interface AuthOptions {
+    /**
+     * The name of the Cognito group that a user must be a member of.
+     * @default 'Admins'
+     */
+    requiredGroup?: string;
+    /**
+     * The name of the custom attribute in the JWT that contains user roles and permissions.
+     * @default 'custom:admin_roles'
+     */
+    customRolesAttribute?: string;
+}
+/**
+ * Extracts and validates authentication and authorization information from an API Gateway event.
+ * This function is now a pure context extractor and does not enforce group membership.
+ *
+ * @param event The APIGatewayProxyEventV2.
+ * @param correlationId Optional correlation ID for logging.
+ * @param options Optional configuration for the custom roles attribute.
+ * @returns An AuthContext object.
+ * @throws Error if unauthorized (e.g., missing claims).
+ */
+export declare function getAuthContext(event: APIGatewayProxyEventV2WithJWTAuthorizer, correlationId?: string, options?: {
+    customRolesAttribute?: string;
+}): AuthContext;
+/**
+ * Higher-order function to wrap Lambda handlers with authentication and authorization.
+ * This middleware enforces membership in a specified Cognito group and provides an
+ * AuthContext for granular permission checks within the handler.
+ *
+ * @param handler The original Lambda handler function, now receiving an `AuthContext` object.
+ * @param options Optional configuration to specify the required group and custom roles attribute.
+ * @returns A new Lambda handler function compatible with API Gateway.
+ */
+export declare function withAdminAuth(handler: (event: APIGatewayProxyEventV2WithJWTAuthorizer, authContext: AuthContext) => Promise<any>, options?: AuthOptions): (event: APIGatewayProxyEventV2WithJWTAuthorizer) => Promise<any>;
+//# sourceMappingURL=authUtils.d.ts.map

package/dist/authUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authUtils.d.ts","sourceRoot":"","sources":["../src/authUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAE1E,OAAO,EAAE,eAAe,EAAE,SAAS,EAA8E,MAAM,mBAAmB,CAAC;AAI3I,eAAO,MAAM,wBAAwB,WAAW,CAAC;AACjD,eAAO,MAAM,4BAA4B,uBAAuB,CAAC;AAEjE,MAAM,WAAW,WAAW;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE;QACd,KAAK,EAAE,SAAS,EAAE,CAAC;QACnB,WAAW,EAAE,eAAe,EAAE,CAAC;KAClC,CAAC;IACF,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,CAAC,UAAU,EAAE,eAAe,KAAK,OAAO,CAAC;CAC3D;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAGD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,uCAAuC,EAC9C,aAAa,CAAC,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE;IAAE,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,WAAW,CAqEb;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CACzB,OAAO,EAAE,CAAC,KAAK,EAAE,uCAAuC,EAAE,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,CAAC,EACnG,OAAO,CAAC,EAAE,WAAW,IAEP,OAAO,uCAAuC,kBAoD/D"}

package/dist/authUtils.js

@@ -0,0 +1,122 @@
+import { buildErrorResponse, createApiGatewayResponse } from './apiResponseBuilder.js';
+import { AdminRole, AdminUserPermissionsSchema, getDefaultPermissionsForRole, isInCognitoGroup } from '@allma/core-types';
+import { log_debug, log_error, log_info, log_warn } from './logger.js';
+// Constants for Cognito group and custom attribute names
+export const ADMIN_COGNITO_GROUP_NAME = 'Admins';
+export const CUSTOM_ADMIN_ROLES_ATTRIBUTE = 'custom:admin_roles';
+/**
+ * Extracts and validates authentication and authorization information from an API Gateway event.
+ * This function is now a pure context extractor and does not enforce group membership.
+ *
+ * @param event The APIGatewayProxyEventV2.
+ * @param correlationId Optional correlation ID for logging.
+ * @param options Optional configuration for the custom roles attribute.
+ * @returns An AuthContext object.
+ * @throws Error if unauthorized (e.g., missing claims).
+ */
+export function getAuthContext(event, correlationId, options) {
+    const claims = event.requestContext.authorizer?.jwt?.claims;
+    if (!claims) {
+        log_warn('Unauthorized: No JWT claims found in event.requestContext.authorizer.', {}, correlationId);
+        throw new Error('Unauthorized');
+    }
+    const userId = claims.sub;
+    const username = claims.email;
+    const cognitoGroupsClaimValue = claims['cognito:groups'];
+    let cognitoGroups = [];
+    if (Array.isArray(cognitoGroupsClaimValue)) {
+        cognitoGroups = cognitoGroupsClaimValue.filter(group => typeof group === 'string');
+        log_debug('Parsed cognito:groups from JWT array.', { rawGroups: cognitoGroupsClaimValue, parsed: cognitoGroups }, correlationId);
+    }
+    else if (typeof cognitoGroupsClaimValue === 'string') {
+        let processableString = cognitoGroupsClaimValue.trim();
+        if (processableString.startsWith('[') && processableString.endsWith(']')) {
+            processableString = processableString.substring(1, processableString.length - 1);
+        }
+        cognitoGroups = processableString.split(',').map(group => group.trim()).filter(group => group.length > 0);
+        log_debug('Parsed cognito:groups from JWT string.', { rawString: cognitoGroupsClaimValue, processedString: processableString, parsed: cognitoGroups }, correlationId);
+    }
+    else if (cognitoGroupsClaimValue !== undefined && cognitoGroupsClaimValue !== null) {
+        log_warn('cognito:groups claim is present but is not an array or string.', { type: typeof cognitoGroupsClaimValue, value: cognitoGroupsClaimValue }, correlationId);
+    }
+    const customRolesAttr = options?.customRolesAttribute || CUSTOM_ADMIN_ROLES_ATTRIBUTE;
+    const customAdminRolesString = claims[customRolesAttr];
+    let adminUserPermissions = { roles: [], permissions: [] };
+    if (typeof customAdminRolesString === 'string') {
+        try {
+            const parsedPermissions = JSON.parse(customAdminRolesString);
+            const validationResult = AdminUserPermissionsSchema.safeParse(parsedPermissions);
+            if (validationResult.success) {
+                adminUserPermissions = validationResult.data;
+            }
+            else {
+                log_warn(`Invalid ${customRolesAttr} attribute format for user.`, { userId, errors: validationResult.error.flatten().fieldErrors }, correlationId);
+            }
+        }
+        catch (e) {
+            log_warn(`Failed to parse ${customRolesAttr} attribute for user.`, { userId, customAdminRolesString, error: e.message }, correlationId);
+        }
+    }
+    const isSuperAdmin = adminUserPermissions.roles.includes(AdminRole.SUPER_ADMIN);
+    const effectivePermissions = new Set();
+    adminUserPermissions.roles.forEach(role => {
+        getDefaultPermissionsForRole(role).forEach(p => effectivePermissions.add(p));
+    });
+    adminUserPermissions.permissions.forEach(p => effectivePermissions.add(p));
+    const authContext = {
+        userId,
+        username,
+        cognitoGroups,
+        adminPermissions: {
+            roles: adminUserPermissions.roles,
+            permissions: Array.from(effectivePermissions),
+        },
+        isAuthenticated: true,
+        isSuperAdmin,
+        hasPermission: (permission) => (isSuperAdmin || effectivePermissions.has(permission)),
+    };
+    log_info(`Admin API request auth context established for user: ${username} (ID: ${userId})`, { groups: cognitoGroups, roles: authContext.adminPermissions.roles, permissions: authContext.adminPermissions.permissions.join(',') }, correlationId);
+    return authContext;
+}
+/**
+ * Higher-order function to wrap Lambda handlers with authentication and authorization.
+ * This middleware enforces membership in a specified Cognito group and provides an
+ * AuthContext for granular permission checks within the handler.
+ *
+ * @param handler The original Lambda handler function, now receiving an `AuthContext` object.
+ * @param options Optional configuration to specify the required group and custom roles attribute.
+ * @returns A new Lambda handler function compatible with API Gateway.
+ */
+export function withAdminAuth(handler, options) {
+    return async (event) => {
+        const correlationId = event.requestContext.requestId || event.headers['X-Correlation-Id'] || 'UNKNOWN';
+        try {
+            // Step 1: Extract context. This will throw 'Unauthorized' if claims are missing.
+            const authContext = getAuthContext(event, correlationId, options?.customRolesAttribute
+                ? { customRolesAttribute: options.customRolesAttribute }
+                : undefined);
+            // Step 2: Enforce group membership.
+            const requiredGroup = options?.requiredGroup || ADMIN_COGNITO_GROUP_NAME;
+            if (!isInCognitoGroup(authContext.cognitoGroups, requiredGroup)) {
+                log_warn(`Forbidden: User '${authContext.username}' (ID: ${authContext.userId}) is not a member of the required '${requiredGroup}' group. User groups: ${authContext.cognitoGroups.join(', ')}`, {}, correlationId);
+                throw new Error('Forbidden');
+            }
+            // Step 3: Call the original handler if authorization succeeds.
+            return await handler(event, authContext);
+        }
+        catch (error) {
+            log_error(`Authorization error in Lambda middleware: ${error.message}`, { errorName: error.name, stack: error.stack }, correlationId);
+            log_error(`Authorization error | event is : ${JSON.stringify(event)}`, {}, correlationId);
+            if (error.message === 'Unauthorized') {
+                return createApiGatewayResponse(401, buildErrorResponse('Unauthorized: Authentication token is missing or invalid.', 'UNAUTHORIZED'), correlationId);
+            }
+            else if (error.message === 'Forbidden') {
+                return createApiGatewayResponse(403, buildErrorResponse('Forbidden: You do not have access to this resource.', 'FORBIDDEN'), correlationId);
+            }
+            else {
+                return createApiGatewayResponse(500, buildErrorResponse('Internal Server Error: Failed to process authentication.', 'SERVER_ERROR'), correlationId);
+            }
+        }
+    };
+}
+//# sourceMappingURL=authUtils.js.map

package/dist/authUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authUtils.js","sourceRoot":"","sources":["../src/authUtils.ts"],"names":[],"mappings":"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"}

package/dist/cdk-utils.d.ts

@@ -0,0 +1,42 @@
+import { Construct } from 'constructs';
+import { StepType } from '@allma/core-types';
+export interface ExternalStepRegistrationProps {
+    /**
+    The name of the central Allma configuration table.
+    */
+    configTableName: string;
+    /**
+    The unique identifier for the step (e.g., 'my-module/my-step').
+    */
+    moduleIdentifier: string;
+    /**
+    The user-friendly name for the step in the UI.
+    */
+    displayName: string;
+    /**
+    A short description of what the step does.
+    */
+    description: string;
+    /**
+    The step's functional type (e.g., DATA_LOAD).
+    */
+    stepType: StepType;
+    /**
+    The ARN of the Lambda function that executes the step's logic.
+    */
+    lambdaArn: string;
+    /**
+    A default configuration object for the step instance when dragged onto the canvas.
+    It will be automatically merged with the moduleIdentifier.
+    */
+    defaultConfig: Record<string, any>;
+}
+/**
+A reusable CDK utility to register an external step in the Allma DynamoDB registry.
+Creates an AwsCustomResource that handles putting the item on deploy/update and deleting it on destroy.
+@param scope The CDK Construct scope.
+@param id The unique ID for this construct.
+@param props The properties for the step registration.
+*/
+export declare function createExternalStepRegistration(scope: Construct, id: string, props: ExternalStepRegistrationProps): void;
+//# sourceMappingURL=cdk-utils.d.ts.map

package/dist/cdk-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdk-utils.d.ts","sourceRoot":"","sources":["../src/cdk-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAKvC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,MAAM,WAAW,6BAA6B;IAC1C;;MAEE;IACF,eAAe,EAAE,MAAM,CAAC;IACxB;;MAEE;IACF,gBAAgB,EAAE,MAAM,CAAC;IACzB;;MAEE;IACF,WAAW,EAAE,MAAM,CAAC;IACpB;;MAEE;IACF,WAAW,EAAE,MAAM,CAAC;IACpB;;MAEE;IACF,QAAQ,EAAE,QAAQ,CAAC;IACnB;;MAEE;IACF,SAAS,EAAE,MAAM,CAAC;IAClB;;;MAGE;IACF,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACtC;AACD;;;;;;EAME;AACF,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,6BAA6B,QAiDhH"}

package/dist/cdk-utils.js

@@ -0,0 +1,62 @@
+import * as cdk from 'aws-cdk-lib';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import { AwsCustomResource, PhysicalResourceId } from 'aws-cdk-lib/custom-resources';
+import { RetentionDays } from 'aws-cdk-lib/aws-logs';
+/**
+A reusable CDK utility to register an external step in the Allma DynamoDB registry.
+Creates an AwsCustomResource that handles putting the item on deploy/update and deleting it on destroy.
+@param scope The CDK Construct scope.
+@param id The unique ID for this construct.
+@param props The properties for the step registration.
+*/
+export function createExternalStepRegistration(scope, id, props) {
+    const { configTableName, moduleIdentifier, displayName, description, stepType, lambdaArn, defaultConfig } = props;
+    const registrationId = `EXTERNAL_STEP#${moduleIdentifier}`;
+    const stack = cdk.Stack.of(scope);
+    const sdkCall = {
+        service: 'DynamoDB',
+        action: 'putItem',
+        parameters: {
+            TableName: configTableName,
+            Item: {
+                PK: { S: registrationId },
+                SK: { S: 'METADATA' },
+                itemType: { S: 'ALLMA_EXTERNAL_STEP_REGISTRY' },
+                moduleIdentifier: { S: moduleIdentifier },
+                lambdaArn: { S: lambdaArn },
+                displayName: { S: displayName },
+                description: { S: description },
+                stepType: { S: stepType },
+                defaultConfig: { S: JSON.stringify({ moduleIdentifier, ...defaultConfig }) },
+            },
+        },
+        physicalResourceId: PhysicalResourceId.of(registrationId),
+    };
+    const deleteCall = {
+        service: 'DynamoDB',
+        action: 'deleteItem',
+        parameters: {
+            TableName: configTableName,
+            Key: {
+                PK: { S: registrationId },
+                SK: { S: 'METADATA' },
+            },
+        },
+    };
+    new AwsCustomResource(scope, id, {
+        onCreate: sdkCall,
+        onUpdate: sdkCall,
+        onDelete: deleteCall,
+        logRetention: RetentionDays.ONE_WEEK,
+        installLatestAwsSdk: true, // Ensures SDK is up-to-date for DynamoDB calls
+        policy: {
+            statements: [
+                new iam.PolicyStatement({
+                    actions: ['dynamodb:PutItem', 'dynamodb:DeleteItem'],
+                    resources: [`arn:aws:dynamodb:${stack.region}:${stack.account}:table/${configTableName}`],
+                }),
+            ],
+        },
+    });
+}
+//# sourceMappingURL=cdk-utils.js.map

package/dist/cdk-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdk-utils.js","sourceRoot":"","sources":["../src/cdk-utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAc,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AACjG,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAiCrD;;;;;;EAME;AACF,MAAM,UAAU,8BAA8B,CAAC,KAAgB,EAAE,EAAU,EAAE,KAAoC;IAC7G,MAAM,EAAE,eAAe,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,KAAK,CAAC;IAClH,MAAM,cAAc,GAAG,iBAAkB,gBAAiB,EAAE,CAAC;IAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,OAAO,GAAe;QACxB,OAAO,EAAE,UAAU;QACnB,MAAM,EAAE,SAAS;QACjB,UAAU,EAAE;YACR,SAAS,EAAE,eAAe;YAC1B,IAAI,EAAE;gBACF,EAAE,EAAE,EAAE,CAAC,EAAE,cAAc,EAAE;gBACzB,EAAE,EAAE,EAAE,CAAC,EAAE,UAAU,EAAE;gBACrB,QAAQ,EAAE,EAAE,CAAC,EAAE,8BAA8B,EAAE;gBAC/C,gBAAgB,EAAE,EAAE,CAAC,EAAE,gBAAgB,EAAE;gBACzC,SAAS,EAAE,EAAE,CAAC,EAAE,SAAS,EAAE;gBAC3B,WAAW,EAAE,EAAE,CAAC,EAAE,WAAW,EAAE;gBAC/B,WAAW,EAAE,EAAE,CAAC,EAAE,WAAW,EAAE;gBAC/B,QAAQ,EAAE,EAAE,CAAC,EAAE,QAAQ,EAAE;gBACzB,aAAa,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,gBAAgB,EAAE,GAAG,aAAa,EAAE,CAAC,EAAE;aAC/E;SACJ;QACD,kBAAkB,EAAE,kBAAkB,CAAC,EAAE,CAAC,cAAc,CAAC;KAC5D,CAAC;IACF,MAAM,UAAU,GAAe;QAC3B,OAAO,EAAE,UAAU;QACnB,MAAM,EAAE,YAAY;QACpB,UAAU,EAAE;YACR,SAAS,EAAE,eAAe;YAC1B,GAAG,EAAE;gBACD,EAAE,EAAE,EAAE,CAAC,EAAE,cAAc,EAAE;gBACzB,EAAE,EAAE,EAAE,CAAC,EAAE,UAAU,EAAE;aACxB;SACJ;KACJ,CAAC;IACF,IAAI,iBAAiB,CAAC,KAAK,EAAE,EAAE,EAAE;QAC7B,QAAQ,EAAE,OAAO;QACjB,QAAQ,EAAE,OAAO;QACjB,QAAQ,EAAE,UAAU;QACpB,YAAY,EAAE,aAAa,CAAC,QAAQ;QACpC,mBAAmB,EAAE,IAAI,EAAE,+CAA+C;QAC1E,MAAM,EAAE;YACJ,UAAU,EAAE;gBACR,IAAI,GAAG,CAAC,eAAe,CAAC;oBACpB,OAAO,EAAE,CAAC,kBAAkB,EAAE,qBAAqB,CAAC;oBACpD,SAAS,EAAE,CAAC,oBAAoB,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,OAAO,UAAU,eAAe,EAAE,CAAC;iBAC5F,CAAC;aACL;SACJ;KACJ,CAAC,CAAC;AACP,CAAC"}

package/dist/cloudformation-utils.d.ts

@@ -0,0 +1,20 @@
+export interface CloudFormationEvent {
+    RequestType: 'Create' | 'Update' | 'Delete';
+    ServiceToken: string;
+    ResponseURL: string;
+    StackId: string;
+    RequestId: string;
+    LogicalResourceId: string;
+    PhysicalResourceId?: string;
+    ResourceType: string;
+    ResourceProperties: {
+        [key: string]: any;
+    };
+    OldResourceProperties?: {
+        [key: string]: any;
+    };
+}
+export declare function sendCloudFormationResponse(event: CloudFormationEvent, status: 'SUCCESS' | 'FAILED', data?: {
+    [key: string]: any;
+}): Promise<void>;
+//# sourceMappingURL=cloudformation-utils.d.ts.map

package/dist/cloudformation-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudformation-utils.d.ts","sourceRoot":"","sources":["../src/cloudformation-utils.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAC;IAC3C,qBAAqB,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAC;CAChD;AAED,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,mBAAmB,EAC1B,MAAM,EAAE,SAAS,GAAG,QAAQ,EAC5B,IAAI,CAAC,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,GAC5B,OAAO,CAAC,IAAI,CAAC,CA0Bf"}

package/dist/cloudformation-utils.js

@@ -0,0 +1,27 @@
+export async function sendCloudFormationResponse(event, status, data) {
+    const responseBody = JSON.stringify({
+        Status: status,
+        Reason: `See the details in CloudWatch Log Stream: ${process.env.AWS_LAMBDA_LOG_STREAM_NAME}`,
+        PhysicalResourceId: event.PhysicalResourceId || `custom-resource-${Date.now()}`,
+        StackId: event.StackId,
+        RequestId: event.RequestId,
+        LogicalResourceId: event.LogicalResourceId,
+        Data: data,
+    });
+    const responseOptions = {
+        method: 'PUT',
+        body: responseBody,
+        headers: {
+            'content-type': '',
+            'content-length': responseBody.length.toString(),
+        },
+    };
+    try {
+        const response = await fetch(event.ResponseURL, responseOptions);
+        console.log('CloudFormation response status:', response.status);
+    }
+    catch (error) {
+        console.error('Failed to send CloudFormation response:', error);
+    }
+}
+//# sourceMappingURL=cloudformation-utils.js.map

package/dist/cloudformation-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudformation-utils.js","sourceRoot":"","sources":["../src/cloudformation-utils.ts"],"names":[],"mappings":"AAaA,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,KAA0B,EAC1B,MAA4B,EAC5B,IAA6B;IAE7B,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC;QAClC,MAAM,EAAE,MAAM;QACd,MAAM,EAAE,6CAA6C,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE;QAC7F,kBAAkB,EAAE,KAAK,CAAC,kBAAkB,IAAI,mBAAmB,IAAI,CAAC,GAAG,EAAE,EAAE;QAC/E,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,IAAI,EAAE,IAAI;KACX,CAAC,CAAC;IAEH,MAAM,eAAe,GAAG;QACtB,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE;YACP,cAAc,EAAE,EAAE;YAClB,gBAAgB,EAAE,YAAY,CAAC,MAAM,CAAC,QAAQ,EAAE;SACjD;KACF,CAAC;IAEF,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;QACjE,OAAO,CAAC,GAAG,CAAC,iCAAiC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,yCAAyC,EAAE,KAAK,CAAC,CAAC;IAClE,CAAC;AACH,CAAC"}

package/dist/hydrationUtils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Recursively traverses an object or array and resolves any S3 pointers it finds.
+ */
+export declare function hydrateInputFromS3Pointers(data: any, correlationId?: string): Promise<any>;
+//# sourceMappingURL=hydrationUtils.d.ts.map

package/dist/hydrationUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrationUtils.d.ts","sourceRoot":"","sources":["../src/hydrationUtils.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,GAAG,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAiBhG"}

package/dist/hydrationUtils.js

@@ -0,0 +1,24 @@
+import { resolveS3Pointer } from './s3Utils.js';
+import { isS3OutputPointerWrapper } from '@allma/core-types';
+/**
+ * Recursively traverses an object or array and resolves any S3 pointers it finds.
+ */
+export async function hydrateInputFromS3Pointers(data, correlationId) {
+    if (Array.isArray(data)) {
+        return Promise.all(data.map(item => hydrateInputFromS3Pointers(item, correlationId)));
+    }
+    if (isS3OutputPointerWrapper(data)) {
+        return resolveS3Pointer(data._s3_output_pointer, correlationId);
+    }
+    if (data && typeof data === 'object') {
+        const hydratedObject = {};
+        for (const key in data) {
+            if (Object.prototype.hasOwnProperty.call(data, key)) {
+                hydratedObject[key] = await hydrateInputFromS3Pointers(data[key], correlationId);
+            }
+        }
+        return hydratedObject;
+    }
+    return data;
+}
+//# sourceMappingURL=hydrationUtils.js.map

package/dist/hydrationUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrationUtils.js","sourceRoot":"","sources":["../src/hydrationUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAE7D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,IAAS,EAAE,aAAsB;IAC9E,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,0BAA0B,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACxF,CAAC;IACD,IAAI,wBAAwB,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,OAAO,gBAAgB,CAAC,IAAI,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,cAAc,GAAwB,EAAE,CAAC;QAC/C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;gBACpD,cAAc,CAAC,GAAG,CAAC,GAAG,MAAM,0BAA0B,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC,CAAC;YACnF,CAAC;QACH,CAAC;QACD,OAAO,cAAc,CAAC;IACxB,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from './apiResponseBuilder.js';
+export * from './authUtils.js';
+export * from './cloudformation-utils.js';
+export * from './hydrationUtils.js';
+export * from './jsonUtils.js';
+export * from './logger.js';
+export * from './s3Utils.js';
+export * from './tokenEstimator.js';
+export * from './storageUtils.js';
+export * from './objectUtils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+export * from './apiResponseBuilder.js';
+export * from './authUtils.js';
+export * from './cloudformation-utils.js';
+export * from './hydrationUtils.js';
+export * from './jsonUtils.js';
+export * from './logger.js';
+export * from './s3Utils.js';
+export * from './tokenEstimator.js';
+export * from './storageUtils.js';
+export * from './objectUtils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC"}

package/dist/jsonUtils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Extracts a potential JSON string from a raw LLM response,
+ * attempts to repair it, and then parses it.
+ * Handles common issues like markdown code fences and leading/trailing text.
+ *
+ * @param inputText The raw string response (for example from the LLM).
+ * @param correlationId Optional correlation ID for logging.
+ * @returns The parsed JSON object.
+ * @throws JsonParseError if parsing fails after repair attempts.
+ */
+export declare function extractAndParseJson(inputText: string, correlationId?: string): any;
+/**
+ * A safer version of extractAndParseJson that returns null on failure instead of throwing.
+ * @param rawLlmResponse The raw string response from the LLM.
+ * @param correlationId Optional correlation ID for logging.
+ * @returns The parsed JSON object or null if parsing fails.
+ */
+export declare function extractAndParseJsonSafe(rawLlmResponse: string, correlationId?: string): any | null;
+//# sourceMappingURL=jsonUtils.d.ts.map

package/dist/jsonUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonUtils.d.ts","sourceRoot":"","sources":["../src/jsonUtils.ts"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,GAAG,CAwFlF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAOlG"}

package/dist/jsonUtils.js

@@ -0,0 +1,117 @@
+import * as jsonrepairModule from 'jsonrepair';
+import { log_debug, log_warn } from './logger.js';
+import { JsonParseError } from '@allma/core-types';
+const repairFunc = jsonrepairModule.jsonrepair || jsonrepairModule;
+/**
+ * Extracts a potential JSON string from a raw LLM response,
+ * attempts to repair it, and then parses it.
+ * Handles common issues like markdown code fences and leading/trailing text.
+ *
+ * @param inputText The raw string response (for example from the LLM).
+ * @param correlationId Optional correlation ID for logging.
+ * @returns The parsed JSON object.
+ * @throws JsonParseError if parsing fails after repair attempts.
+ */
+export function extractAndParseJson(inputText, correlationId) {
+    if (typeof repairFunc !== 'function') {
+        // This will give a very clear error in logs if the import fails.
+        throw new JsonParseError('Critical error: jsonrepair function could not be imported correctly.');
+    }
+    if (!inputText || inputText.trim() === "") {
+        log_warn('Cannot parse empty or whitespace-only LLM response.', { correlationId });
+        throw new JsonParseError("Raw LLM response is empty or whitespace.", { rawResponse: inputText });
+    }
+    let textToParse = inputText.trim();
+    // Attempt to remove markdown fences (```json ... ``` or ``` ... ```)
+    // Regex to capture content within ```json ... ``` or ``` ... ```
+    const markdownJsonRegex = /^```(?:json)?\s*([\s\S]*?)\s*```$/m;
+    const markdownMatch = textToParse.match(markdownJsonRegex);
+    if (markdownMatch && markdownMatch[1]) {
+        textToParse = markdownMatch[1].trim();
+        log_debug('Removed markdown fences from LLM response.', { correlationId });
+    }
+    // Fallback: if no markdown, try to find the outermost JSON structure.
+    // This helps if there's leading/trailing text without markdown.
+    if (!(markdownMatch && markdownMatch[1])) {
+        const firstBrace = textToParse.indexOf('{');
+        const firstBracket = textToParse.indexOf('[');
+        let startIndex = -1;
+        if (firstBrace !== -1 && firstBracket !== -1) {
+            startIndex = Math.min(firstBrace, firstBracket);
+        }
+        else if (firstBrace !== -1) {
+            startIndex = firstBrace;
+        }
+        else if (firstBracket !== -1) {
+            startIndex = firstBracket;
+        }
+        if (startIndex !== -1) {
+            const lastBrace = textToParse.lastIndexOf('}');
+            const lastBracket = textToParse.lastIndexOf(']');
+            let endIndex = -1;
+            if (lastBrace !== -1 && lastBracket !== -1) {
+                endIndex = Math.max(lastBrace, lastBracket);
+            }
+            else if (lastBrace !== -1) {
+                endIndex = lastBrace;
+            }
+            else if (lastBracket !== -1) {
+                endIndex = lastBracket;
+            }
+            if (endIndex > startIndex) {
+                const extractedSubstring = textToParse.substring(startIndex, endIndex + 1);
+                // Basic sanity check: does the substring look plausible?
+                // (e.g. starts with { and ends with } or starts with [ and ends with ])
+                const firstChar = extractedSubstring.charAt(0);
+                const lastChar = extractedSubstring.charAt(extractedSubstring.length - 1);
+                if ((firstChar === '{' && lastChar === '}') || (firstChar === '[' && lastChar === ']')) {
+                    textToParse = extractedSubstring;
+                    log_debug('Extracted potential JSON substring from surrounding text.', { correlationId });
+                }
+                else {
+                    log_debug('Found start/end braces/brackets, but they did not form a plausible outer pair. Will attempt repair on mostly original text.', { correlationId });
+                }
+            }
+            else {
+                log_debug('Could not determine a clear JSON substring from braces/brackets. Attempting repair on (markdown-stripped) text.', { correlationId });
+            }
+        }
+        else {
+            log_debug('No braces or brackets found. Attempting repair on (markdown-stripped) text.', { correlationId });
+        }
+    }
+    try {
+        const repairedJsonString = repairFunc(textToParse);
+        //const repairedJsonString = JSON.parse(textToParse);
+        log_debug('LLM response string repaired, attempting JSON.parse.', { correlationId });
+        return JSON.parse(repairedJsonString);
+    }
+    catch (error) {
+        log_warn('Failed to parse JSON even after attempting extraction and repair.', {
+            originalTextPreview: inputText.substring(0, 2000),
+            processedTextPreview: textToParse.substring(0, 2000),
+            error: error.message,
+            correlationId
+        });
+        throw new JsonParseError(`Failed to parse JSON object from LLM response: ${error.message}`, {
+            rawResponseSnippet: inputText.substring(0, 2000),
+            attemptedToParseSnippet: textToParse.substring(0, 2000)
+        }, error);
+    }
+}
+/**
+ * A safer version of extractAndParseJson that returns null on failure instead of throwing.
+ * @param rawLlmResponse The raw string response from the LLM.
+ * @param correlationId Optional correlation ID for logging.
+ * @returns The parsed JSON object or null if parsing fails.
+ */
+export function extractAndParseJsonSafe(rawLlmResponse, correlationId) {
+    try {
+        return extractAndParseJson(rawLlmResponse, correlationId);
+    }
+    catch (e) {
+        // Error is already logged by extractAndParseJson
+        return null;
+    }
+}
+//# sourceMappingURL=jsonUtils.js.map

package/dist/jsonUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonUtils.js","sourceRoot":"","sources":["../src/jsonUtils.ts"],"names":[],"mappings":"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"}

package/dist/logger.d.ts

@@ -0,0 +1,6 @@
+export declare const log_debug: (message: string, details?: object, correlationId?: string) => void;
+export declare const log_info: (message: string, details?: object, correlationId?: string) => void;
+export declare const log_warn: (message: string, details?: object, correlationId?: string) => void;
+export declare const log_error: (message: string, details?: object, correlationId?: string) => void;
+export declare const log_critical: (message: string, details?: object, correlationId?: string) => void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AA+BA,eAAO,MAAM,SAAS,GAAI,SAAS,MAAM,EAAE,UAAS,MAAW,EAAE,gBAAgB,MAAM,SAAyD,CAAC;AACjJ,eAAO,MAAM,QAAQ,GAAI,SAAS,MAAM,EAAE,UAAS,MAAW,EAAE,gBAAgB,MAAM,SAAwD,CAAC;AAC/I,eAAO,MAAM,QAAQ,GAAI,SAAS,MAAM,EAAE,UAAS,MAAW,EAAE,gBAAgB,MAAM,SAAwD,CAAC;AAC/I,eAAO,MAAM,SAAS,GAAI,SAAS,MAAM,EAAE,UAAS,MAAW,EAAE,gBAAgB,MAAM,SAAyD,CAAC;AACjJ,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,EAAE,UAAS,MAAW,EAAE,gBAAgB,MAAM,SAA4D,CAAC"}

package/dist/logger.js

@@ -0,0 +1,31 @@
+import { LogLevel } from '@allma/core-types';
+const LOG_LEVELS = Object.values(LogLevel);
+// Default to 'INFO' if LOG_LEVEL is not set or is invalid
+let currentLogLevel = process.env.LOG_LEVEL?.toUpperCase() || LogLevel.INFO;
+if (!LOG_LEVELS.includes(currentLogLevel)) {
+    console.log(`Invalid LOG_LEVEL: "${process.env.LOG_LEVEL}". Defaulting to INFO.`);
+    currentLogLevel = LogLevel.INFO;
+}
+const LOG_LEVEL_NUMERIC = LOG_LEVELS.indexOf(currentLogLevel);
+const log = (level, message, details = {}, correlationId) => {
+    const messageLevelNumeric = LOG_LEVELS.indexOf(level);
+    // Only log if the message's level is at or above the current log level
+    if (messageLevelNumeric >= LOG_LEVEL_NUMERIC) {
+        const timestamp = new Date().toISOString();
+        const logEntry = {
+            level: level,
+            message,
+            correlationId: correlationId || 'N/A',
+            ...details,
+            timestamp,
+        };
+        // Using console.log for all levels; CloudWatch will handle them as log events.
+        console.log(JSON.stringify(logEntry));
+    }
+};
+export const log_debug = (message, details = {}, correlationId) => log(LogLevel.DEBUG, message, details, correlationId);
+export const log_info = (message, details = {}, correlationId) => log(LogLevel.INFO, message, details, correlationId);
+export const log_warn = (message, details = {}, correlationId) => log(LogLevel.WARN, message, details, correlationId);
+export const log_error = (message, details = {}, correlationId) => log(LogLevel.ERROR, message, details, correlationId);
+export const log_critical = (message, details = {}, correlationId) => log(LogLevel.CRITICAL, message, details, correlationId);
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAE3C,0DAA0D;AAC1D,IAAI,eAAe,GAAc,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,WAAW,EAAe,IAAI,QAAQ,CAAC,IAAI,CAAC;AACpG,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;IACxC,OAAO,CAAC,GAAG,CAAC,uBAAuB,OAAO,CAAC,GAAG,CAAC,SAAS,wBAAwB,CAAC,CAAC;IAClF,eAAe,GAAG,QAAQ,CAAC,IAAI,CAAC;AACpC,CAAC;AACD,MAAM,iBAAiB,GAAG,UAAU,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;AAG9D,MAAM,GAAG,GAAG,CAAC,KAAe,EAAE,OAAe,EAAE,UAAkB,EAAE,EAAE,aAAsB,EAAE,EAAE;IAC7F,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAEtD,uEAAuE;IACvE,IAAI,mBAAmB,IAAI,iBAAiB,EAAE,CAAC;QAC7C,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,QAAQ,GAAG;YACf,KAAK,EAAE,KAAK;YACZ,OAAO;YACP,aAAa,EAAE,aAAa,IAAI,KAAK;YACrC,GAAG,OAAO;YACV,SAAS;SACV,CAAC;QACF,+EAA+E;QAC/E,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxC,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,OAAe,EAAE,UAAkB,EAAE,EAAE,aAAsB,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;AACjJ,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAAe,EAAE,UAAkB,EAAE,EAAE,aAAsB,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;AAC/I,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAAe,EAAE,UAAkB,EAAE,EAAE,aAAsB,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;AAC/I,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,OAAe,EAAE,UAAkB,EAAE,EAAE,aAAsB,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;AACjJ,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,UAAkB,EAAE,EAAE,aAAsB,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC"}

package/dist/objectUtils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A utility to check if an item is a non-array, non-null object.
+ */
+export declare function isObject(item: any): item is Record<string, any>;
+/**
+ * Deeply merges two objects. The source object's properties overwrite the target's.
+ * Properties with `undefined` values in the source are ignored to prevent accidental overwrites.
+ * @param target The target object.
+ * @param source The source object.
+ * @returns A new object with the merged properties.
+ */
+export declare function deepMerge<T extends Record<string, any>>(target: T, source: Record<string, any>): T;
+//# sourceMappingURL=objectUtils.d.ts.map

package/dist/objectUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"objectUtils.d.ts","sourceRoot":"","sources":["../src/objectUtils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAE/D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAyBlG"}

package/dist/objectUtils.js

@@ -0,0 +1,38 @@
+/**
+ * A utility to check if an item is a non-array, non-null object.
+ */
+export function isObject(item) {
+    return (item && typeof item === 'object' && !Array.isArray(item));
+}
+/**
+ * Deeply merges two objects. The source object's properties overwrite the target's.
+ * Properties with `undefined` values in the source are ignored to prevent accidental overwrites.
+ * @param target The target object.
+ * @param source The source object.
+ * @returns A new object with the merged properties.
+ */
+export function deepMerge(target, source) {
+    const output = { ...target };
+    if (isObject(target) && isObject(source)) {
+        for (const key of Object.keys(source)) {
+            const sourceValue = source[key];
+            // Do not merge if the source value is undefined. This prevents
+            // optional properties in override objects (like from branch definitions)
+            // from overwriting existing defined values with 'undefined'.
+            if (sourceValue === undefined) {
+                continue;
+            }
+            const targetValue = target[key];
+            if (isObject(targetValue) && isObject(sourceValue)) {
+                // If both values are objects, recurse
+                output[key] = deepMerge(targetValue, sourceValue);
+            }
+            else {
+                // Otherwise, the source value (which is not undefined) overwrites the target value
+                output[key] = sourceValue;
+            }
+        }
+    }
+    return output;
+}
+//# sourceMappingURL=objectUtils.js.map

package/dist/objectUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"objectUtils.js","sourceRoot":"","sources":["../src/objectUtils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAS;IAC9B,OAAO,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAgC,MAAS,EAAE,MAA2B;IAC3F,MAAM,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;IAC7B,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACvC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACpC,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAEhC,+DAA+D;YAC/D,yEAAyE;YACzE,6DAA6D;YAC7D,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;gBAC5B,SAAS;YACb,CAAC;YAED,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAEhC,IAAI,QAAQ,CAAC,WAAW,CAAC,IAAI,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;gBACjD,sCAAsC;gBACrC,MAAc,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;YAC/D,CAAC;iBAAM,CAAC;gBACJ,mFAAmF;gBAClF,MAAc,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC;YACvC,CAAC;QACL,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC"}

package/dist/s3Utils.d.ts

@@ -0,0 +1,18 @@
+import type { S3OutputPointerWrapper, S3Pointer } from '@allma/core-types';
+/**
+ * Fetches the actual data from an S3 pointer.
+ */
+export declare function resolveS3Pointer(s3Pointer: S3Pointer, correlationId?: string): Promise<Record<string, any>>;
+/**
+ * Checks the size of a payload and offloads it to S3 if it exceeds the defined threshold.
+ * This is a generic utility for any Lambda to use for its return payload.
+ *
+ * @param payload The object to potentially offload.
+ * @param bucketName The S3 bucket to upload to.
+ * @param keyPrefix A prefix for the S3 key (e.g., 'step_outputs/flow-id/step-id').
+ * @param correlationId For logging.
+ * @param thresholdBytes The size threshold to trigger offloading. Defaults to the configured environment variable.
+ * @returns The original payload if it's small, or an S3OutputPointerWrapper if it was offloaded.
+ */
+export declare function offloadIfLarge(payload: Record<string, any> | undefined, bucketName: string, keyPrefix: string, correlationId: string, thresholdBytes?: number): Promise<Record<string, any> | S3OutputPointerWrapper | undefined>;
+//# sourceMappingURL=s3Utils.d.ts.map

package/dist/s3Utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3Utils.d.ts","sourceRoot":"","sources":["../src/s3Utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAY3E;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,SAAS,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAiBjH;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EACxC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,cAAc,GAAE,MAAwC,GACzD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,sBAAsB,GAAG,SAAS,CAAC,CAgCnE"}

package/dist/s3Utils.js

@@ -0,0 +1,69 @@
+import { S3Client, GetObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3';
+import { ENV_VAR_NAMES } from '@allma/core-types';
+import { log_info, log_error, log_warn, log_debug } from "./logger.js";
+const s3Client = new S3Client({});
+const MAX_CONTEXT_DATA_SIZE_BYTES_DEFAULT = 10 * 1024; // 10KB default
+const PAYLOAD_OFFLOAD_THRESHOLD_BYTES = process.env[ENV_VAR_NAMES.MAX_CONTEXT_DATA_SIZE_BYTES]
+    ? parseInt(process.env[ENV_VAR_NAMES.MAX_CONTEXT_DATA_SIZE_BYTES] || '', 10)
+    : MAX_CONTEXT_DATA_SIZE_BYTES_DEFAULT;
+/**
+ * Fetches the actual data from an S3 pointer.
+ */
+export async function resolveS3Pointer(s3Pointer, correlationId) {
+    log_info('Resolving S3 data pointer', { s3Pointer }, correlationId);
+    try {
+        const command = new GetObjectCommand({
+            Bucket: s3Pointer.bucket,
+            Key: s3Pointer.key,
+        });
+        const { Body } = await s3Client.send(command);
+        if (Body) {
+            const content = await Body.transformToString();
+            return JSON.parse(content);
+        }
+        throw new Error('S3 object body for data pointer is empty.');
+    }
+    catch (e) {
+        log_error('Failed to fetch or parse data from S3 pointer', { s3Pointer, error: e.message }, correlationId);
+        throw new Error(`Failed to resolve S3 data pointer: ${e.message}`);
+    }
+}
+/**
+ * Checks the size of a payload and offloads it to S3 if it exceeds the defined threshold.
+ * This is a generic utility for any Lambda to use for its return payload.
+ *
+ * @param payload The object to potentially offload.
+ * @param bucketName The S3 bucket to upload to.
+ * @param keyPrefix A prefix for the S3 key (e.g., 'step_outputs/flow-id/step-id').
+ * @param correlationId For logging.
+ * @param thresholdBytes The size threshold to trigger offloading. Defaults to the configured environment variable.
+ * @returns The original payload if it's small, or an S3OutputPointerWrapper if it was offloaded.
+ */
+export async function offloadIfLarge(payload, bucketName, keyPrefix, correlationId, thresholdBytes = PAYLOAD_OFFLOAD_THRESHOLD_BYTES) {
+    if (!payload)
+        return undefined;
+    try {
+        const payloadString = JSON.stringify(payload);
+        const payloadSize = Buffer.byteLength(payloadString, 'utf-8');
+        log_debug(`offloadIfLarge for ${bucketName} ${keyPrefix}...`, { thresholdBytes }, correlationId);
+        if (payloadSize > thresholdBytes) {
+            const s3Key = `${keyPrefix}_${new Date().toISOString()}.json`;
+            log_warn(`Payload is large (${payloadSize} bytes). Offloading to S3.`, { s3Key, thresholdBytes }, correlationId);
+            await s3Client.send(new PutObjectCommand({
+                Bucket: bucketName,
+                Key: s3Key,
+                Body: payloadString,
+                ContentType: 'application/json',
+            }));
+            const s3Pointer = { bucket: bucketName, key: s3Key };
+            return { _s3_output_pointer: s3Pointer }; // Return the wrapper
+        }
+        // Payload is small enough, return as is
+        return payload;
+    }
+    catch (e) {
+        log_error(`Failed to offload payload to S3 for key prefix '${keyPrefix}'`, { error: e.message }, correlationId);
+        throw new Error(`Failed during S3 offload attempt: ${e.message}`);
+    }
+}
+//# sourceMappingURL=s3Utils.js.map

package/dist/s3Utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3Utils.js","sourceRoot":"","sources":["../src/s3Utils.ts"],"names":[],"mappings":"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"}

package/dist/storageUtils.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { PromptTemplateSchema, PromptTemplateVersionStorageItem } from '@allma/core-types';
+/**
+ * Converts a DynamoDB storage item to its corresponding API type by stripping storage-specific keys.
+ * This is a generic helper for the application's data access layer.
+ * @param item The storage item from DynamoDB.
+ * @returns The item formatted as its API type.
+ */
+export declare function fromStorageItem<T extends {
+    PK: string;
+    SK: string;
+    itemType: string;
+}, U>(item: T): U;
+/**
+ * Converts a PromptTemplate API object to its DynamoDB storage representation.
+ * This helper is specific to the application's data access layer for prompt templates.
+ * @param apiItem The PromptTemplate object.
+ * @returns The validated storage item for a prompt version.
+ * @throws An error if the constructed item fails validation.
+ */
+export declare function toPromptTemplateVersionStorageItem(apiItem: z.infer<typeof PromptTemplateSchema>): PromptTemplateVersionStorageItem;
+//# sourceMappingURL=storageUtils.d.ts.map

package/dist/storageUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageUtils.d.ts","sourceRoot":"","sources":["../src/storageUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACH,oBAAoB,EAEpB,gCAAgC,EAEnC,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAGrG;AAED;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,GAAG,gCAAgC,CAYlI"}

package/dist/storageUtils.js

@@ -0,0 +1,32 @@
+import { PromptTemplateVersionStorageItemSchema, ITEM_TYPE_ALLMA_PROMPT_TEMPLATE, } from '@allma/core-types';
+/**
+ * Converts a DynamoDB storage item to its corresponding API type by stripping storage-specific keys.
+ * This is a generic helper for the application's data access layer.
+ * @param item The storage item from DynamoDB.
+ * @returns The item formatted as its API type.
+ */
+export function fromStorageItem(item) {
+    const { PK: _, SK: __, itemType: ___, ...apiItem } = item;
+    return apiItem;
+}
+/**
+ * Converts a PromptTemplate API object to its DynamoDB storage representation.
+ * This helper is specific to the application's data access layer for prompt templates.
+ * @param apiItem The PromptTemplate object.
+ * @returns The validated storage item for a prompt version.
+ * @throws An error if the constructed item fails validation.
+ */
+export function toPromptTemplateVersionStorageItem(apiItem) {
+    const storageItem = {
+        ...apiItem,
+        PK: `PROMPT_TEMPLATE#${apiItem.id}`,
+        SK: `VERSION#${apiItem.version}`,
+        itemType: ITEM_TYPE_ALLMA_PROMPT_TEMPLATE,
+    };
+    const validationResult = PromptTemplateVersionStorageItemSchema.safeParse(storageItem);
+    if (!validationResult.success) {
+        throw new Error(`Internal data integrity error: Constructed PromptTemplate version storage item is invalid: ${validationResult.error.message}`);
+    }
+    return validationResult.data;
+}
+//# sourceMappingURL=storageUtils.js.map

package/dist/storageUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageUtils.js","sourceRoot":"","sources":["../src/storageUtils.ts"],"names":[],"mappings":"AACA,OAAO,EAEH,sCAAsC,EAEtC,+BAA+B,GAClC,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAA4D,IAAO;IAC9F,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,IAAI,CAAC;IAC1D,OAAO,OAAY,CAAC;AACxB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kCAAkC,CAAC,OAA6C;IAC5F,MAAM,WAAW,GAAqC;QAClD,GAAG,OAAO;QACV,EAAE,EAAE,mBAAmB,OAAO,CAAC,EAAE,EAAE;QACnC,EAAE,EAAE,WAAW,OAAO,CAAC,OAAO,EAAE;QAChC,QAAQ,EAAE,+BAA+B;KAC5C,CAAC;IACF,MAAM,gBAAgB,GAAG,sCAAsC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IACvF,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,8FAA8F,gBAAgB,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IACpJ,CAAC;IACD,OAAO,gBAAgB,CAAC,IAAI,CAAC;AACjC,CAAC"}

package/dist/tokenEstimator.d.ts

@@ -0,0 +1,2 @@
+export declare function estimateTokens(text: string | null | undefined, correlationId?: string): number;
+//# sourceMappingURL=tokenEstimator.d.ts.map

package/dist/tokenEstimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenEstimator.d.ts","sourceRoot":"","sources":["../src/tokenEstimator.ts"],"names":[],"mappings":"AA6BA,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAc9F"}

package/dist/tokenEstimator.js

@@ -0,0 +1,45 @@
+import { log_error, log_warn, log_info } from './logger.js';
+import { Tiktoken } from "js-tiktoken";
+import o200k_base from "js-tiktoken/ranks/o200k_base";
+// Cache the Tiktoken instance globally within this module
+let tokenizerInstance = null;
+let tokenizerInitialized = false;
+function getTokenizer(correlationId) {
+    if (!tokenizerInstance) {
+        if (tokenizerInitialized) { // It failed before, don't retry endlessly in one invocation
+            log_error('Tokenizer previously failed to initialize. Using fallback.', {}, correlationId);
+            throw new Error('Tokenizer previously failed to initialize.'); // Forces fallback in estimateTokens
+        }
+        try {
+            tokenizerInstance = new Tiktoken(o200k_base);
+            tokenizerInitialized = true; // Mark as initialized (or attempted)
+            log_info('Tiktoken (o200k_base) tokenizer initialized successfully.', {}, correlationId || 'TOKENIZER_INIT');
+        }
+        catch (e) {
+            tokenizerInitialized = true; // Mark as attempted to prevent re-init loops
+            log_error('Failed to initialize tiktoken tokenizer (o200k_base). Subsequent calls will use fallback.', {
+                error: e.message,
+            }, correlationId || 'TOKENIZER_INIT_ERROR');
+            throw new Error(`Critical: Failed to initialize tokenizer: ${e.message}`);
+        }
+    }
+    return tokenizerInstance;
+}
+export function estimateTokens(text, correlationId) {
+    if (!text)
+        return 0;
+    try {
+        const enc = getTokenizer(correlationId);
+        return enc.encode(text).length;
+    }
+    catch (e) {
+        log_warn('Failed to estimate tokens using tiktoken. Falling back to character-based estimation. This is highly inaccurate.', {
+            error: e.message,
+            textSnippet: text.substring(0, 100),
+            correlationId
+        });
+        // Fallback: very rough estimate (char count / 4)
+        return Math.ceil(text.length / 4);
+    }
+}
+//# sourceMappingURL=tokenEstimator.js.map

package/dist/tokenEstimator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenEstimator.js","sourceRoot":"","sources":["../src/tokenEstimator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,UAAU,MAAM,8BAA8B,CAAC;AAEtD,0DAA0D;AAC1D,IAAI,iBAAiB,GAAoB,IAAI,CAAC;AAC9C,IAAI,oBAAoB,GAAG,KAAK,CAAC;AAEjC,SAAS,YAAY,CAAC,aAAsB;IACxC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACrB,IAAI,oBAAoB,EAAE,CAAC,CAAC,4DAA4D;YACpF,SAAS,CAAC,4DAA4D,EAAE,EAAE,EAAE,aAAa,CAAC,CAAC;YAC3F,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC,CAAC,oCAAoC;QACvG,CAAC;QACD,IAAI,CAAC;YACD,iBAAiB,GAAG,IAAI,QAAQ,CAAC,UAAU,CAAC,CAAC;YAC7C,oBAAoB,GAAG,IAAI,CAAC,CAAC,qCAAqC;YAClE,QAAQ,CAAC,2DAA2D,EAAE,EAAE,EAAE,aAAa,IAAI,gBAAgB,CAAC,CAAC;QACjH,CAAC;QAAC,OAAO,CAAM,EAAE,CAAC;YACd,oBAAoB,GAAG,IAAI,CAAC,CAAC,6CAA6C;YAC1E,SAAS,CAAC,2FAA2F,EAAE;gBACnG,KAAK,EAAE,CAAC,CAAC,OAAO;aACnB,EAAE,aAAa,IAAI,sBAAsB,CAAC,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9E,CAAC;IACL,CAAC;IACD,OAAO,iBAAiB,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAA+B,EAAE,aAAsB;IAClF,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IACpB,IAAI,CAAC;QACD,MAAM,GAAG,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;QACxC,OAAO,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;IACnC,CAAC;IAAC,OAAO,CAAM,EAAE,CAAC;QACd,QAAQ,CAAC,kHAAkH,EAAE;YACzH,KAAK,EAAE,CAAC,CAAC,OAAO;YAChB,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC;YACnC,aAAa;SAChB,CAAC,CAAC;QACH,iDAAiD;QACjD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACtC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@allma/core-sdk",
+  "version": "1.0.1",
+  "description": "Core SDK with shared utilities (logging, auth, S3 utils) for building on the Allma serverless AI orchestration platform.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint ."
+  },
+  "author": "@webjema",
+  "license": "Apache-2.0",
+  "homepage": "https://docs.allma.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ALLMA-dev/allma-core.git",
+    "directory": "packages/core-sdk"
+  },
+  "keywords": [
+    "allma",
+    "sdk",
+    "aws",
+    "lambda",
+    "utilities",
+    "serverless",
+    "ai",
+    "orchestration"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@allma/core-types": "^1.0.1",
+    "@aws-sdk/client-s3": "^3.500.0",
+    "@aws-sdk/client-secrets-manager": "^3.500.0",
+    "@aws-sdk/client-sns": "^3.500.0",
+    "@aws-sdk/client-sqs": "^3.500.0",
+    "@aws-sdk/client-ssm": "^3.500.0",
+    "@aws-sdk/client-sfn": "^3.500.0",
+    "@aws-sdk/lib-dynamodb": "^3.500.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "eslint": "^9.8.0",
+    "typescript-eslint": "^8.0.0"
+  }
+}