@fnd-platform/api 1.0.0-alpha.2 → 1.0.0-alpha.4

package/lib/lib/errors.js

@@ -1,4 +1,4 @@
-'use strict';
+"use strict";
 /**
  * Custom error classes for API responses.
  *
@@ -7,14 +7,8 @@
  *
  * @packageDocumentation
  */
-Object.defineProperty(exports, '__esModule', { value: true });
-exports.ConflictError =
-  exports.ForbiddenError =
-  exports.UnauthorizedError =
-  exports.ValidationError =
-  exports.NotFoundError =
-  exports.ApiError =
-    void 0;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConflictError = exports.ForbiddenError = exports.UnauthorizedError = exports.ValidationError = exports.NotFoundError = exports.ApiError = void 0;
 /**
  * Base API error class.
  *
@@ -29,38 +23,38 @@ exports.ConflictError =
  * ```
  */
 class ApiError extends Error {
-  code;
-  statusCode;
-  details;
-  /**
-   * Creates a new ApiError.
-   *
-   * @param message - Human-readable error message
-   * @param code - Machine-readable error code (UPPER_SNAKE_CASE)
-   * @param statusCode - HTTP status code (default: 500)
-   * @param details - Optional additional error details
-   */
-  constructor(message, code, statusCode = 500, details) {
-    super(message);
-    this.code = code;
-    this.statusCode = statusCode;
-    this.details = details;
-    this.name = 'ApiError';
-    // Maintains proper stack trace for where error was thrown
-    Error.captureStackTrace(this, this.constructor);
-  }
-  /**
-   * Converts the error to a JSON-serializable object.
-   *
-   * @returns Object with code, message, and details
-   */
-  toJSON() {
-    return {
-      code: this.code,
-      message: this.message,
-      details: this.details,
-    };
-  }
+    code;
+    statusCode;
+    details;
+    /**
+     * Creates a new ApiError.
+     *
+     * @param message - Human-readable error message
+     * @param code - Machine-readable error code (UPPER_SNAKE_CASE)
+     * @param statusCode - HTTP status code (default: 500)
+     * @param details - Optional additional error details
+     */
+    constructor(message, code, statusCode = 500, details) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.details = details;
+        this.name = 'ApiError';
+        // Maintains proper stack trace for where error was thrown
+        Error.captureStackTrace(this, this.constructor);
+    }
+    /**
+     * Converts the error to a JSON-serializable object.
+     *
+     * @returns Object with code, message, and details
+     */
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            details: this.details,
+        };
+    }
 }
 exports.ApiError = ApiError;
 /**
@@ -74,10 +68,10 @@ exports.ApiError = ApiError;
  * ```
  */
 class NotFoundError extends ApiError {
-  constructor(message = 'Resource not found') {
-    super(message, 'NOT_FOUND', 404);
-    this.name = 'NotFoundError';
-  }
+    constructor(message = 'Resource not found') {
+        super(message, 'NOT_FOUND', 404);
+        this.name = 'NotFoundError';
+    }
 }
 exports.NotFoundError = NotFoundError;
 /**
@@ -92,10 +86,10 @@ exports.NotFoundError = NotFoundError;
  * ```
  */
 class ValidationError extends ApiError {
-  constructor(message = 'Validation failed', details) {
-    super(message, 'VALIDATION_ERROR', 400, details);
-    this.name = 'ValidationError';
-  }
+    constructor(message = 'Validation failed', details) {
+        super(message, 'VALIDATION_ERROR', 400, details);
+        this.name = 'ValidationError';
+    }
 }
 exports.ValidationError = ValidationError;
 /**
@@ -109,10 +103,10 @@ exports.ValidationError = ValidationError;
  * ```
  */
 class UnauthorizedError extends ApiError {
-  constructor(message = 'Unauthorized') {
-    super(message, 'UNAUTHORIZED', 401);
-    this.name = 'UnauthorizedError';
-  }
+    constructor(message = 'Unauthorized') {
+        super(message, 'UNAUTHORIZED', 401);
+        this.name = 'UnauthorizedError';
+    }
 }
 exports.UnauthorizedError = UnauthorizedError;
 /**
@@ -127,10 +121,10 @@ exports.UnauthorizedError = UnauthorizedError;
  * ```
  */
 class ForbiddenError extends ApiError {
-  constructor(message = 'Forbidden') {
-    super(message, 'FORBIDDEN', 403);
-    this.name = 'ForbiddenError';
-  }
+    constructor(message = 'Forbidden') {
+        super(message, 'FORBIDDEN', 403);
+        this.name = 'ForbiddenError';
+    }
 }
 exports.ForbiddenError = ForbiddenError;
 /**
@@ -145,10 +139,10 @@ exports.ForbiddenError = ForbiddenError;
  * ```
  */
 class ConflictError extends ApiError {
-  constructor(message = 'Resource conflict') {
-    super(message, 'CONFLICT', 409);
-    this.name = 'ConflictError';
-  }
+    constructor(message = 'Resource conflict') {
+        super(message, 'CONFLICT', 409);
+        this.name = 'ConflictError';
+    }
 }
 exports.ConflictError = ConflictError;
-//# sourceMappingURL=errors.js.map
+//# sourceMappingURL=errors.js.map

package/lib/lib/keys.d.ts

@@ -0,0 +1,122 @@
+/**
+ * DynamoDB key builders for single-table design.
+ *
+ * These helpers generate consistent key structures for content entities
+ * following the fnd-platform single-table design patterns.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Key structure for DynamoDB primary key.
+ */
+export interface PrimaryKey {
+    PK: string;
+    SK: string;
+}
+/**
+ * Key structure for GSI1 (slug lookup).
+ */
+export interface GSI1Key {
+    GSI1PK: string;
+    GSI1SK: string;
+}
+/**
+ * Key structure for GSI2 (type/status listing).
+ */
+export interface GSI2Key {
+    GSI2PK: string;
+    GSI2SK: string;
+}
+/**
+ * Content key builders for DynamoDB operations.
+ *
+ * @example
+ * ```typescript
+ * // Get primary key for content item
+ * const pk = contentKeys.pk('content-123');
+ * const sk = contentKeys.sk();
+ *
+ * // Build GSI1 keys for slug lookup
+ * const gsi1Keys = contentKeys.gsi1.bySlug('my-blog-post');
+ *
+ * // Build GSI2 keys for listing by type
+ * const gsi2Keys = contentKeys.gsi2.byType('blog-post', '2024-01-15T12:00:00Z');
+ * ```
+ */
+export declare const contentKeys: {
+    /**
+     * Generate partition key for content item.
+     * @param id - Content ID
+     * @returns Formatted partition key
+     */
+    pk: (id: string) => string;
+    /**
+     * Generate sort key for content item.
+     * @returns Constant sort key for content
+     */
+    sk: () => string;
+    /**
+     * Generate full primary key for content item.
+     * @param id - Content ID
+     * @returns Primary key object
+     */
+    keys: (id: string) => PrimaryKey;
+    /**
+     * GSI1 key builders for slug-based lookups.
+     */
+    gsi1: {
+        /**
+         * Generate GSI1 keys for looking up content by slug.
+         * @param slug - Content slug
+         * @returns GSI1 key object
+         */
+        bySlug: (slug: string) => GSI1Key;
+    };
+    /**
+     * GSI2 key builders for listing content by type.
+     */
+    gsi2: {
+        /**
+         * Generate GSI2 keys for listing content by type with timestamp sorting.
+         * @param contentType - Content type (e.g., 'blog-post', 'page')
+         * @param timestamp - ISO 8601 timestamp for sort ordering
+         * @returns GSI2 key object
+         */
+        byType: (contentType: string, timestamp: string) => GSI2Key;
+    };
+};
+/**
+ * User key builders for DynamoDB operations.
+ *
+ * @example
+ * ```typescript
+ * // Get primary key for user profile
+ * const pk = userKeys.pk('user-123');
+ * const sk = userKeys.sk.profile();
+ * ```
+ */
+export declare const userKeys: {
+    /**
+     * Generate partition key for user.
+     * @param id - User ID (Cognito sub)
+     * @returns Formatted partition key
+     */
+    pk: (id: string) => string;
+    /**
+     * Sort key generators for user-related items.
+     */
+    sk: {
+        /**
+         * Generate sort key for user profile.
+         * @returns Profile sort key
+         */
+        profile: () => string;
+    };
+    /**
+     * Generate full primary key for user profile.
+     * @param id - User ID
+     * @returns Primary key object
+     */
+    keys: (id: string) => PrimaryKey;
+};
+//# sourceMappingURL=keys.d.ts.map

package/lib/lib/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/lib/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW;IACtB;;;;OAIG;aACM,MAAM,KAAG,MAAM;IAExB;;;OAGG;cACK,MAAM;IAEd;;;;OAIG;eACQ,MAAM,KAAG,UAAU;IAK9B;;OAEG;;QAED;;;;WAIG;uBACY,MAAM,KAAG,OAAO;;IAMjC;;OAEG;;QAED;;;;;WAKG;8BACmB,MAAM,aAAa,MAAM,KAAG,OAAO;;CAK5D,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ;IACnB;;;;OAIG;aACM,MAAM,KAAG,MAAM;IAExB;;OAEG;;QAED;;;WAGG;uBACU,MAAM;;IAGrB;;;;OAIG;eACQ,MAAM,KAAG,UAAU;CAI/B,CAAC"}

package/lib/lib/keys.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * DynamoDB key builders for single-table design.
+ *
+ * These helpers generate consistent key structures for content entities
+ * following the fnd-platform single-table design patterns.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userKeys = exports.contentKeys = void 0;
+/**
+ * Content key builders for DynamoDB operations.
+ *
+ * @example
+ * ```typescript
+ * // Get primary key for content item
+ * const pk = contentKeys.pk('content-123');
+ * const sk = contentKeys.sk();
+ *
+ * // Build GSI1 keys for slug lookup
+ * const gsi1Keys = contentKeys.gsi1.bySlug('my-blog-post');
+ *
+ * // Build GSI2 keys for listing by type
+ * const gsi2Keys = contentKeys.gsi2.byType('blog-post', '2024-01-15T12:00:00Z');
+ * ```
+ */
+exports.contentKeys = {
+    /**
+     * Generate partition key for content item.
+     * @param id - Content ID
+     * @returns Formatted partition key
+     */
+    pk: (id) => `CONTENT#${id}`,
+    /**
+     * Generate sort key for content item.
+     * @returns Constant sort key for content
+     */
+    sk: () => 'CONTENT',
+    /**
+     * Generate full primary key for content item.
+     * @param id - Content ID
+     * @returns Primary key object
+     */
+    keys: (id) => ({
+        PK: exports.contentKeys.pk(id),
+        SK: exports.contentKeys.sk(),
+    }),
+    /**
+     * GSI1 key builders for slug-based lookups.
+     */
+    gsi1: {
+        /**
+         * Generate GSI1 keys for looking up content by slug.
+         * @param slug - Content slug
+         * @returns GSI1 key object
+         */
+        bySlug: (slug) => ({
+            GSI1PK: `CONTENT#SLUG#${slug}`,
+            GSI1SK: 'CONTENT',
+        }),
+    },
+    /**
+     * GSI2 key builders for listing content by type.
+     */
+    gsi2: {
+        /**
+         * Generate GSI2 keys for listing content by type with timestamp sorting.
+         * @param contentType - Content type (e.g., 'blog-post', 'page')
+         * @param timestamp - ISO 8601 timestamp for sort ordering
+         * @returns GSI2 key object
+         */
+        byType: (contentType, timestamp) => ({
+            GSI2PK: contentType,
+            GSI2SK: timestamp,
+        }),
+    },
+};
+/**
+ * User key builders for DynamoDB operations.
+ *
+ * @example
+ * ```typescript
+ * // Get primary key for user profile
+ * const pk = userKeys.pk('user-123');
+ * const sk = userKeys.sk.profile();
+ * ```
+ */
+exports.userKeys = {
+    /**
+     * Generate partition key for user.
+     * @param id - User ID (Cognito sub)
+     * @returns Formatted partition key
+     */
+    pk: (id) => `USER#${id}`,
+    /**
+     * Sort key generators for user-related items.
+     */
+    sk: {
+        /**
+         * Generate sort key for user profile.
+         * @returns Profile sort key
+         */
+        profile: () => 'PROFILE',
+    },
+    /**
+     * Generate full primary key for user profile.
+     * @param id - User ID
+     * @returns Primary key object
+     */
+    keys: (id) => ({
+        PK: exports.userKeys.pk(id),
+        SK: exports.userKeys.sk.profile(),
+    }),
+};
+//# sourceMappingURL=keys.js.map

package/lib/lib/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../src/lib/keys.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AA0BH;;;;;;;;;;;;;;;GAeG;AACU,QAAA,WAAW,GAAG;IACzB;;;;OAIG;IACH,EAAE,EAAE,CAAC,EAAU,EAAU,EAAE,CAAC,WAAW,EAAE,EAAE;IAE3C;;;OAGG;IACH,EAAE,EAAE,GAAW,EAAE,CAAC,SAAS;IAE3B;;;;OAIG;IACH,IAAI,EAAE,CAAC,EAAU,EAAc,EAAE,CAAC,CAAC;QACjC,EAAE,EAAE,mBAAW,CAAC,EAAE,CAAC,EAAE,CAAC;QACtB,EAAE,EAAE,mBAAW,CAAC,EAAE,EAAE;KACrB,CAAC;IAEF;;OAEG;IACH,IAAI,EAAE;QACJ;;;;WAIG;QACH,MAAM,EAAE,CAAC,IAAY,EAAW,EAAE,CAAC,CAAC;YAClC,MAAM,EAAE,gBAAgB,IAAI,EAAE;YAC9B,MAAM,EAAE,SAAS;SAClB,CAAC;KACH;IAED;;OAEG;IACH,IAAI,EAAE;QACJ;;;;;WAKG;QACH,MAAM,EAAE,CAAC,WAAmB,EAAE,SAAiB,EAAW,EAAE,CAAC,CAAC;YAC5D,MAAM,EAAE,WAAW;YACnB,MAAM,EAAE,SAAS;SAClB,CAAC;KACH;CACF,CAAC;AAEF;;;;;;;;;GASG;AACU,QAAA,QAAQ,GAAG;IACtB;;;;OAIG;IACH,EAAE,EAAE,CAAC,EAAU,EAAU,EAAE,CAAC,QAAQ,EAAE,EAAE;IAExC;;OAEG;IACH,EAAE,EAAE;QACF;;;WAGG;QACH,OAAO,EAAE,GAAW,EAAE,CAAC,SAAS;KACjC;IAED;;;;OAIG;IACH,IAAI,EAAE,CAAC,EAAU,EAAc,EAAE,CAAC,CAAC;QACjC,EAAE,EAAE,gBAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QACnB,EAAE,EAAE,gBAAQ,CAAC,EAAE,CAAC,OAAO,EAAE;KAC1B,CAAC;CACH,CAAC"}

package/lib/middleware/auth.js

@@ -1,12 +1,12 @@
-'use strict';
+"use strict";
 /**
  * Authentication middleware for Lambda handlers.
  *
  * @packageDocumentation
  */
-Object.defineProperty(exports, '__esModule', { value: true });
+Object.defineProperty(exports, "__esModule", { value: true });
 exports.withAuth = withAuth;
-const response_1 = require('../lib/response');
+const response_1 = require("../lib/response");
 /**
  * Middleware that validates JWT tokens from Cognito.
  *
@@ -37,26 +37,26 @@ const response_1 = require('../lib/response');
  * ```
  */
 function withAuth(options = {}) {
-  const { roles, skipPaths = [] } = options;
-  return (handler) => async (event, context) => {
-    // Skip auth for certain paths
-    if (skipPaths.some((path) => event.path?.includes(path))) {
-      return handler(event, context);
-    }
-    // Get claims from API Gateway authorizer
-    const claims = event.requestContext?.authorizer?.claims;
-    if (!claims || !claims.sub) {
-      return (0, response_1.unauthorized)('Missing or invalid authentication');
-    }
-    // Check role requirements
-    if (roles && roles.length > 0) {
-      const userGroups = claims['cognito:groups'] || [];
-      const hasRequiredRole = roles.some((role) => userGroups.includes(role));
-      if (!hasRequiredRole) {
-        return (0, response_1.forbidden)(`Required role: ${roles.join(' or ')}`);
-      }
-    }
-    return handler(event, context);
-  };
+    const { roles, skipPaths = [] } = options;
+    return (handler) => async (event, context) => {
+        // Skip auth for certain paths
+        if (skipPaths.some((path) => event.path?.includes(path))) {
+            return handler(event, context);
+        }
+        // Get claims from API Gateway authorizer
+        const claims = event.requestContext?.authorizer?.claims;
+        if (!claims || !claims.sub) {
+            return (0, response_1.unauthorized)('Missing or invalid authentication');
+        }
+        // Check role requirements
+        if (roles && roles.length > 0) {
+            const userGroups = claims['cognito:groups'] || [];
+            const hasRequiredRole = roles.some((role) => userGroups.includes(role));
+            if (!hasRequiredRole) {
+                return (0, response_1.forbidden)(`Required role: ${roles.join(' or ')}`);
+            }
+        }
+        return handler(event, context);
+    };
 }
-//# sourceMappingURL=auth.js.map
+//# sourceMappingURL=auth.js.map

package/lib/middleware/cors.js

@@ -1,10 +1,10 @@
-'use strict';
+"use strict";
 /**
  * CORS middleware for Lambda handlers.
  *
  * @packageDocumentation
  */
-Object.defineProperty(exports, '__esModule', { value: true });
+Object.defineProperty(exports, "__esModule", { value: true });
 exports.withCors = withCors;
 /**
  * Middleware that adds CORS headers to responses.
@@ -25,38 +25,33 @@ exports.withCors = withCors;
  * ```
  */
 function withCors(options = {}) {
-  const {
-    origin = '*',
-    methods = ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
-    headers = ['Content-Type', 'Authorization'],
-    credentials = false,
-  } = options;
-  const corsHeaders = {
-    'Access-Control-Allow-Origin': Array.isArray(origin) ? origin[0] : origin,
-    'Access-Control-Allow-Methods': methods.join(','),
-    'Access-Control-Allow-Headers': headers.join(','),
-  };
-  if (credentials) {
-    corsHeaders['Access-Control-Allow-Credentials'] = 'true';
-  }
-  return (handler) => async (event, context) => {
-    // Handle preflight requests
-    if (event.httpMethod === 'OPTIONS') {
-      return {
-        statusCode: 204,
-        headers: corsHeaders,
-        body: '',
-      };
+    const { origin = '*', methods = ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'], headers = ['Content-Type', 'Authorization'], credentials = false, } = options;
+    const corsHeaders = {
+        'Access-Control-Allow-Origin': Array.isArray(origin) ? origin[0] : origin,
+        'Access-Control-Allow-Methods': methods.join(','),
+        'Access-Control-Allow-Headers': headers.join(','),
+    };
+    if (credentials) {
+        corsHeaders['Access-Control-Allow-Credentials'] = 'true';
     }
-    const response = await handler(event, context);
-    // Merge CORS headers with response headers
-    return {
-      ...response,
-      headers: {
-        ...response.headers,
-        ...corsHeaders,
-      },
+    return (handler) => async (event, context) => {
+        // Handle preflight requests
+        if (event.httpMethod === 'OPTIONS') {
+            return {
+                statusCode: 204,
+                headers: corsHeaders,
+                body: '',
+            };
+        }
+        const response = await handler(event, context);
+        // Merge CORS headers with response headers
+        return {
+            ...response,
+            headers: {
+                ...response.headers,
+                ...corsHeaders,
+            },
+        };
     };
-  };
 }
-//# sourceMappingURL=cors.js.map
+//# sourceMappingURL=cors.js.map

package/lib/middleware/error-handler.js

@@ -1,13 +1,13 @@
-'use strict';
+"use strict";
 /**
  * Error handling middleware for Lambda handlers.
  *
  * @packageDocumentation
  */
-Object.defineProperty(exports, '__esModule', { value: true });
+Object.defineProperty(exports, "__esModule", { value: true });
 exports.withErrorHandler = withErrorHandler;
-const response_1 = require('../lib/response');
-const errors_1 = require('../lib/errors');
+const response_1 = require("../lib/response");
+const errors_1 = require("../lib/errors");
 /**
  * Middleware that catches errors and returns appropriate error responses.
  *
@@ -29,21 +29,22 @@ const errors_1 = require('../lib/errors');
  * ```
  */
 function withErrorHandler(options = {}) {
-  const { logErrors = true } = options;
-  return (handler) => async (event, context) => {
-    try {
-      return await handler(event, context);
-    } catch (err) {
-      if (logErrors) {
-        console.error('Handler error:', err);
-      }
-      if (err instanceof errors_1.ApiError) {
-        return (0, response_1.error)(err, err.statusCode);
-      }
-      // Unknown errors become 500
-      const message = err instanceof Error ? err.message : 'Internal server error';
-      return (0, response_1.error)(message, 500);
-    }
-  };
+    const { logErrors = true } = options;
+    return (handler) => async (event, context) => {
+        try {
+            return await handler(event, context);
+        }
+        catch (err) {
+            if (logErrors) {
+                console.error('Handler error:', err);
+            }
+            if (err instanceof errors_1.ApiError) {
+                return (0, response_1.error)(err, err.statusCode);
+            }
+            // Unknown errors become 500
+            const message = err instanceof Error ? err.message : 'Internal server error';
+            return (0, response_1.error)(message, 500);
+        }
+    };
 }
-//# sourceMappingURL=error-handler.js.map
+//# sourceMappingURL=error-handler.js.map