@back23/promptly-sdk 1.1.0 → 1.2.0

package/dist/index.d.mts

@@ -13,6 +13,31 @@ interface ApiResponse<T> {
     data: T;
     message?: string;
 }
+/**
+ * Pagination metadata
+ */
+interface PaginationMeta {
+    current_page: number;
+    last_page: number;
+    per_page: number;
+    total: number;
+    from: number | null;
+    to: number | null;
+}
+/**
+ * Unified list response - ALWAYS returns this structure for list APIs
+ * - data is ALWAYS an array (never null/undefined)
+ * - meta contains pagination info
+ */
+interface ListResponse<T> {
+    /** Array of items - guaranteed to be an array (empty if no data) */
+    data: T[];
+    /** Pagination metadata */
+    meta: PaginationMeta;
+}
+/**
+ * @deprecated Use ListResponse<T> instead. Kept for backward compatibility.
+ */
 interface PaginatedResponse<T> {
     data: T[];
     meta: {
@@ -644,6 +669,11 @@ declare class HttpClient {
      * GET request
      */
     get<T>(endpoint: string, params?: Record<string, any>): Promise<T>;
+    /**
+     * GET request for list endpoints - ALWAYS returns normalized ListResponse
+     * Guarantees: data is always an array, meta is always present
+     */
+    getList<T>(endpoint: string, params?: Record<string, any>): Promise<ListResponse<T>>;
     /**
      * POST request
      */
@@ -740,16 +770,18 @@ declare class BoardsResource {
     constructor(http: HttpClient);
     /**
      * List all boards
+     * @returns ListResponse with data array (always defined) and pagination meta
      */
-    list(params?: BoardListParams): Promise<Board[]>;
+    list(params?: BoardListParams): Promise<ListResponse<Board>>;
     /**
      * Get board by ID or slug
      */
     get(idOrSlug: number | string): Promise<Board>;
     /**
      * List posts in a board
+     * @returns ListResponse with data array and pagination meta
      */
-    listPosts(boardIdOrSlug: number | string, params?: PostListParams): Promise<PaginatedResponse<BoardPost>>;
+    listPosts(boardIdOrSlug: number | string, params?: PostListParams): Promise<ListResponse<BoardPost>>;
     /**
      * Get post by ID
      */
@@ -768,6 +800,7 @@ declare class BoardsResource {
     deletePost(postId: number): Promise<void>;
     /**
      * List comments for a post
+     * @returns Array of comments (always an array, never null/undefined)
      */
     listComments(postId: number): Promise<BoardComment[]>;
     /**
@@ -793,8 +826,9 @@ declare class BlogResource {
     constructor(http: HttpClient);
     /**
      * List blog posts
+     * @returns ListResponse with data array (always defined) and pagination meta
      */
-    list(params?: BlogListParams): Promise<PaginatedResponse<BlogPost>>;
+    list(params?: BlogListParams): Promise<ListResponse<BlogPost>>;
     /**
      * Get blog post by slug
      */
@@ -805,26 +839,32 @@ declare class BlogResource {
     getById(id: number): Promise<BlogPost>;
     /**
      * Get featured blog posts
+     * @returns Array of featured posts (always an array, never null/undefined)
      */
     featured(limit?: number): Promise<BlogPost[]>;
     /**
      * Get blog posts by category
+     * @returns ListResponse with data array and pagination meta
      */
-    byCategory(category: string, params?: Omit<BlogListParams, 'category'>): Promise<PaginatedResponse<BlogPost>>;
+    byCategory(category: string, params?: Omit<BlogListParams, 'category'>): Promise<ListResponse<BlogPost>>;
     /**
      * Get blog posts by tag
+     * @returns ListResponse with data array and pagination meta
      */
-    byTag(tag: string, params?: Omit<BlogListParams, 'tag'>): Promise<PaginatedResponse<BlogPost>>;
+    byTag(tag: string, params?: Omit<BlogListParams, 'tag'>): Promise<ListResponse<BlogPost>>;
     /**
      * Search blog posts
+     * @returns ListResponse with data array and pagination meta
      */
-    search(query: string, params?: Omit<BlogListParams, 'search'>): Promise<PaginatedResponse<BlogPost>>;
+    search(query: string, params?: Omit<BlogListParams, 'search'>): Promise<ListResponse<BlogPost>>;
     /**
      * Get blog categories
+     * @returns Array of category names (always an array)
      */
     categories(): Promise<string[]>;
     /**
      * Get blog tags
+     * @returns Array of tag names (always an array)
      */
     tags(): Promise<string[]>;
 }
@@ -838,8 +878,9 @@ declare class FormsResource {
     constructor(http: HttpClient);
     /**
      * List all forms
+     * @returns ListResponse with data array and pagination meta
      */
-    list(params?: FormListParams): Promise<Form[]>;
+    list(params?: FormListParams): Promise<ListResponse<Form>>;
     /**
      * Get form by ID or slug
      */
@@ -850,8 +891,9 @@ declare class FormsResource {
     submit(formIdOrSlug: number | string, data: SubmitFormData): Promise<FormSubmission>;
     /**
      * Get my form submissions
+     * @returns ListResponse with data array and pagination meta
      */
-    mySubmissions(params?: SubmissionListParams): Promise<PaginatedResponse<FormSubmission>>;
+    mySubmissions(params?: SubmissionListParams): Promise<ListResponse<FormSubmission>>;
     /**
      * Get specific submission
      */
@@ -867,22 +909,26 @@ declare class ShopResource {
     constructor(http: HttpClient);
     /**
      * List products
+     * @returns ListResponse with data array and pagination meta
      */
-    listProducts(params?: ProductListParams): Promise<PaginatedResponse<Product>>;
+    listProducts(params?: ProductListParams): Promise<ListResponse<Product>>;
     /**
      * Get product by ID or slug
      */
     getProduct(idOrSlug: number | string): Promise<Product>;
     /**
      * Get featured products
+     * @returns Array of featured products (always an array)
      */
     featuredProducts(limit?: number): Promise<Product[]>;
     /**
      * Search products
+     * @returns ListResponse with data array and pagination meta
      */
-    searchProducts(query: string, params?: Omit<ProductListParams, 'search'>): Promise<PaginatedResponse<Product>>;
+    searchProducts(query: string, params?: Omit<ProductListParams, 'search'>): Promise<ListResponse<Product>>;
     /**
      * List product categories
+     * @returns Array of categories (always an array)
      */
     listCategories(): Promise<ProductCategory[]>;
     /**
@@ -891,8 +937,9 @@ declare class ShopResource {
     getCategory(idOrSlug: number | string): Promise<ProductCategory>;
     /**
      * Get products in category
+     * @returns ListResponse with data array and pagination meta
      */
-    categoryProducts(categoryIdOrSlug: number | string, params?: Omit<ProductListParams, 'category'>): Promise<PaginatedResponse<Product>>;
+    categoryProducts(categoryIdOrSlug: number | string, params?: Omit<ProductListParams, 'category'>): Promise<ListResponse<Product>>;
     /**
      * Get current cart
      */
@@ -915,8 +962,9 @@ declare class ShopResource {
     clearCart(): Promise<void>;
     /**
      * List my orders
+     * @returns ListResponse with data array and pagination meta
      */
-    listOrders(params?: OrderListParams): Promise<PaginatedResponse<Order>>;
+    listOrders(params?: OrderListParams): Promise<ListResponse<Order>>;
     /**
      * Get order by ID or order number
      */
@@ -954,6 +1002,7 @@ declare class ShopResource {
     validateCoupon(code: string, orderAmount: number): Promise<CouponValidation>;
     /**
      * Get available coupons for current user
+     * @returns Array of coupons (always an array)
      */
     myCoupons(): Promise<Coupon[]>;
 }
@@ -990,19 +1039,12 @@ declare class MediaResource {
     delete(mediaId: number): Promise<void>;
 }
 
-/**
- * Custom Entities Resource for Promptly SDK
- *
- * Provides access to dynamically created data structures.
- * AI can create custom entities through MCP, and this SDK allows
- * frontend applications to interact with them.
- */
-
 declare class EntitiesResource {
     private http;
     constructor(http: HttpClient);
     /**
      * List all active custom entities
+     * @returns Array of entities (always an array)
      *
      * @example
      * ```typescript
@@ -1023,6 +1065,7 @@ declare class EntitiesResource {
     getSchema(slug: string): Promise<EntitySchema>;
     /**
      * List records for an entity
+     * @returns ListResponse with data array and pagination meta
      *
      * @example
      * ```typescript
@@ -1042,7 +1085,7 @@ declare class EntitiesResource {
      * });
      * ```
      */
-    listRecords(slug: string, params?: EntityListParams): Promise<PaginatedResponse<EntityRecord>>;
+    listRecords(slug: string, params?: EntityListParams): Promise<ListResponse<EntityRecord>>;
     /**
      * Get a single record by ID
      *
@@ -1123,18 +1166,7 @@ declare class EntitiesResource {
             data: Array<Omit<EntityRecord, "data"> & {
                 data: T;
             }>;
-            meta: {
-                current_page: number;
-                last_page: number;
-                per_page: number;
-                total: number;
-            };
-            links?: {
-                first: string;
-                last: string;
-                prev: string | null;
-                next: string | null;
-            };
+            meta: PaginationMeta;
         }>;
         get: (id: number) => Promise<Omit<EntityRecord, "data"> & {
             data: T;
@@ -1218,4 +1250,4 @@ declare class Promptly {
     getToken(): string | null;
 }
 
-export { type AddToCartData, type ApiError, type ApiResponse, type ApplyCouponData, type AuthResponse, type BlogListParams, type BlogPost, type Board, type BoardComment, type BoardListParams, type BoardPost, type BoardSettings, type Cart, type CartItem, type Coupon, type CouponType, type CouponValidation, type CreateCommentData, type CreateEntityRecordData, type CreateOrderData, type CreatePostData, type CustomEntity, type EntityField, type EntityListParams, type EntityRecord, type EntitySchema, type ForgotPasswordData, type Form, type FormField, type FormFieldOption, type FormFieldType, type FormFieldValidation, type FormListParams, type FormSettings, type FormSubmission, type ListParams, type LoginCredentials, type Media, type Member, type Order, type OrderItem, type OrderListParams, type OrderStatus, type PaginatedResponse, type Payment, type PaymentCancelData, type PaymentConfirmData, type PaymentMethod, type PaymentReadyData, type PaymentStatus, type PostListParams, type Product, type ProductCategory, type ProductListParams, type ProductOption, type ProductOptionValue, type ProductStatus, type ProductVariant, Promptly, type PromptlyConfig, PromptlyError, type RegisterData, type ResetPasswordData, type SocialAuthUrl, type SocialProvider, type SubmissionListParams, type SubmitFormData, type UpdateCartItemData, type UpdateCommentData, type UpdateEntityRecordData, type UpdatePostData, type UpdateProfileData, Promptly as default };
+export { type AddToCartData, type ApiError, type ApiResponse, type ApplyCouponData, type AuthResponse, type BlogListParams, type BlogPost, type Board, type BoardComment, type BoardListParams, type BoardPost, type BoardSettings, type Cart, type CartItem, type Coupon, type CouponType, type CouponValidation, type CreateCommentData, type CreateEntityRecordData, type CreateOrderData, type CreatePostData, type CustomEntity, type EntityField, type EntityListParams, type EntityRecord, type EntitySchema, type ForgotPasswordData, type Form, type FormField, type FormFieldOption, type FormFieldType, type FormFieldValidation, type FormListParams, type FormSettings, type FormSubmission, type ListParams, type ListResponse, type LoginCredentials, type Media, type Member, type Order, type OrderItem, type OrderListParams, type OrderStatus, type PaginatedResponse, type PaginationMeta, type Payment, type PaymentCancelData, type PaymentConfirmData, type PaymentMethod, type PaymentReadyData, type PaymentStatus, type PostListParams, type Product, type ProductCategory, type ProductListParams, type ProductOption, type ProductOptionValue, type ProductStatus, type ProductVariant, Promptly, type PromptlyConfig, PromptlyError, type RegisterData, type ResetPasswordData, type SocialAuthUrl, type SocialProvider, type SubmissionListParams, type SubmitFormData, type UpdateCartItemData, type UpdateCommentData, type UpdateEntityRecordData, type UpdatePostData, type UpdateProfileData, Promptly as default };

package/dist/index.d.ts

@@ -13,6 +13,31 @@ interface ApiResponse<T> {
     data: T;
     message?: string;
 }
+/**
+ * Pagination metadata
+ */
+interface PaginationMeta {
+    current_page: number;
+    last_page: number;
+    per_page: number;
+    total: number;
+    from: number | null;
+    to: number | null;
+}
+/**
+ * Unified list response - ALWAYS returns this structure for list APIs
+ * - data is ALWAYS an array (never null/undefined)
+ * - meta contains pagination info
+ */
+interface ListResponse<T> {
+    /** Array of items - guaranteed to be an array (empty if no data) */
+    data: T[];
+    /** Pagination metadata */
+    meta: PaginationMeta;
+}
+/**
+ * @deprecated Use ListResponse<T> instead. Kept for backward compatibility.
+ */
 interface PaginatedResponse<T> {
     data: T[];
     meta: {
@@ -644,6 +669,11 @@ declare class HttpClient {
      * GET request
      */
     get<T>(endpoint: string, params?: Record<string, any>): Promise<T>;
+    /**
+     * GET request for list endpoints - ALWAYS returns normalized ListResponse
+     * Guarantees: data is always an array, meta is always present
+     */
+    getList<T>(endpoint: string, params?: Record<string, any>): Promise<ListResponse<T>>;
     /**
      * POST request
      */
@@ -740,16 +770,18 @@ declare class BoardsResource {
     constructor(http: HttpClient);
     /**
      * List all boards
+     * @returns ListResponse with data array (always defined) and pagination meta
      */
-    list(params?: BoardListParams): Promise<Board[]>;
+    list(params?: BoardListParams): Promise<ListResponse<Board>>;
     /**
      * Get board by ID or slug
      */
     get(idOrSlug: number | string): Promise<Board>;
     /**
      * List posts in a board
+     * @returns ListResponse with data array and pagination meta
      */
-    listPosts(boardIdOrSlug: number | string, params?: PostListParams): Promise<PaginatedResponse<BoardPost>>;
+    listPosts(boardIdOrSlug: number | string, params?: PostListParams): Promise<ListResponse<BoardPost>>;
     /**
      * Get post by ID
      */
@@ -768,6 +800,7 @@ declare class BoardsResource {
     deletePost(postId: number): Promise<void>;
     /**
      * List comments for a post
+     * @returns Array of comments (always an array, never null/undefined)
      */
     listComments(postId: number): Promise<BoardComment[]>;
     /**
@@ -793,8 +826,9 @@ declare class BlogResource {
     constructor(http: HttpClient);
     /**
      * List blog posts
+     * @returns ListResponse with data array (always defined) and pagination meta
      */
-    list(params?: BlogListParams): Promise<PaginatedResponse<BlogPost>>;
+    list(params?: BlogListParams): Promise<ListResponse<BlogPost>>;
     /**
      * Get blog post by slug
      */
@@ -805,26 +839,32 @@ declare class BlogResource {
     getById(id: number): Promise<BlogPost>;
     /**
      * Get featured blog posts
+     * @returns Array of featured posts (always an array, never null/undefined)
      */
     featured(limit?: number): Promise<BlogPost[]>;
     /**
      * Get blog posts by category
+     * @returns ListResponse with data array and pagination meta
      */
-    byCategory(category: string, params?: Omit<BlogListParams, 'category'>): Promise<PaginatedResponse<BlogPost>>;
+    byCategory(category: string, params?: Omit<BlogListParams, 'category'>): Promise<ListResponse<BlogPost>>;
     /**
      * Get blog posts by tag
+     * @returns ListResponse with data array and pagination meta
      */
-    byTag(tag: string, params?: Omit<BlogListParams, 'tag'>): Promise<PaginatedResponse<BlogPost>>;
+    byTag(tag: string, params?: Omit<BlogListParams, 'tag'>): Promise<ListResponse<BlogPost>>;
     /**
      * Search blog posts
+     * @returns ListResponse with data array and pagination meta
      */
-    search(query: string, params?: Omit<BlogListParams, 'search'>): Promise<PaginatedResponse<BlogPost>>;
+    search(query: string, params?: Omit<BlogListParams, 'search'>): Promise<ListResponse<BlogPost>>;
     /**
      * Get blog categories
+     * @returns Array of category names (always an array)
      */
     categories(): Promise<string[]>;
     /**
      * Get blog tags
+     * @returns Array of tag names (always an array)
      */
     tags(): Promise<string[]>;
 }
@@ -838,8 +878,9 @@ declare class FormsResource {
     constructor(http: HttpClient);
     /**
      * List all forms
+     * @returns ListResponse with data array and pagination meta
      */
-    list(params?: FormListParams): Promise<Form[]>;
+    list(params?: FormListParams): Promise<ListResponse<Form>>;
     /**
      * Get form by ID or slug
      */
@@ -850,8 +891,9 @@ declare class FormsResource {
     submit(formIdOrSlug: number | string, data: SubmitFormData): Promise<FormSubmission>;
     /**
      * Get my form submissions
+     * @returns ListResponse with data array and pagination meta
      */
-    mySubmissions(params?: SubmissionListParams): Promise<PaginatedResponse<FormSubmission>>;
+    mySubmissions(params?: SubmissionListParams): Promise<ListResponse<FormSubmission>>;
     /**
      * Get specific submission
      */
@@ -867,22 +909,26 @@ declare class ShopResource {
     constructor(http: HttpClient);
     /**
      * List products
+     * @returns ListResponse with data array and pagination meta
      */
-    listProducts(params?: ProductListParams): Promise<PaginatedResponse<Product>>;
+    listProducts(params?: ProductListParams): Promise<ListResponse<Product>>;
     /**
      * Get product by ID or slug
      */
     getProduct(idOrSlug: number | string): Promise<Product>;
     /**
      * Get featured products
+     * @returns Array of featured products (always an array)
      */
     featuredProducts(limit?: number): Promise<Product[]>;
     /**
      * Search products
+     * @returns ListResponse with data array and pagination meta
      */
-    searchProducts(query: string, params?: Omit<ProductListParams, 'search'>): Promise<PaginatedResponse<Product>>;
+    searchProducts(query: string, params?: Omit<ProductListParams, 'search'>): Promise<ListResponse<Product>>;
     /**
      * List product categories
+     * @returns Array of categories (always an array)
      */
     listCategories(): Promise<ProductCategory[]>;
     /**
@@ -891,8 +937,9 @@ declare class ShopResource {
     getCategory(idOrSlug: number | string): Promise<ProductCategory>;
     /**
      * Get products in category
+     * @returns ListResponse with data array and pagination meta
      */
-    categoryProducts(categoryIdOrSlug: number | string, params?: Omit<ProductListParams, 'category'>): Promise<PaginatedResponse<Product>>;
+    categoryProducts(categoryIdOrSlug: number | string, params?: Omit<ProductListParams, 'category'>): Promise<ListResponse<Product>>;
     /**
      * Get current cart
      */
@@ -915,8 +962,9 @@ declare class ShopResource {
     clearCart(): Promise<void>;
     /**
      * List my orders
+     * @returns ListResponse with data array and pagination meta
      */
-    listOrders(params?: OrderListParams): Promise<PaginatedResponse<Order>>;
+    listOrders(params?: OrderListParams): Promise<ListResponse<Order>>;
     /**
      * Get order by ID or order number
      */
@@ -954,6 +1002,7 @@ declare class ShopResource {
     validateCoupon(code: string, orderAmount: number): Promise<CouponValidation>;
     /**
      * Get available coupons for current user
+     * @returns Array of coupons (always an array)
      */
     myCoupons(): Promise<Coupon[]>;
 }
@@ -990,19 +1039,12 @@ declare class MediaResource {
     delete(mediaId: number): Promise<void>;
 }
 
-/**
- * Custom Entities Resource for Promptly SDK
- *
- * Provides access to dynamically created data structures.
- * AI can create custom entities through MCP, and this SDK allows
- * frontend applications to interact with them.
- */
-
 declare class EntitiesResource {
     private http;
     constructor(http: HttpClient);
     /**
      * List all active custom entities
+     * @returns Array of entities (always an array)
      *
      * @example
      * ```typescript
@@ -1023,6 +1065,7 @@ declare class EntitiesResource {
     getSchema(slug: string): Promise<EntitySchema>;
     /**
      * List records for an entity
+     * @returns ListResponse with data array and pagination meta
      *
      * @example
      * ```typescript
@@ -1042,7 +1085,7 @@ declare class EntitiesResource {
      * });
      * ```
      */
-    listRecords(slug: string, params?: EntityListParams): Promise<PaginatedResponse<EntityRecord>>;
+    listRecords(slug: string, params?: EntityListParams): Promise<ListResponse<EntityRecord>>;
     /**
      * Get a single record by ID
      *
@@ -1123,18 +1166,7 @@ declare class EntitiesResource {
             data: Array<Omit<EntityRecord, "data"> & {
                 data: T;
             }>;
-            meta: {
-                current_page: number;
-                last_page: number;
-                per_page: number;
-                total: number;
-            };
-            links?: {
-                first: string;
-                last: string;
-                prev: string | null;
-                next: string | null;
-            };
+            meta: PaginationMeta;
         }>;
         get: (id: number) => Promise<Omit<EntityRecord, "data"> & {
             data: T;
@@ -1218,4 +1250,4 @@ declare class Promptly {
     getToken(): string | null;
 }
 
-export { type AddToCartData, type ApiError, type ApiResponse, type ApplyCouponData, type AuthResponse, type BlogListParams, type BlogPost, type Board, type BoardComment, type BoardListParams, type BoardPost, type BoardSettings, type Cart, type CartItem, type Coupon, type CouponType, type CouponValidation, type CreateCommentData, type CreateEntityRecordData, type CreateOrderData, type CreatePostData, type CustomEntity, type EntityField, type EntityListParams, type EntityRecord, type EntitySchema, type ForgotPasswordData, type Form, type FormField, type FormFieldOption, type FormFieldType, type FormFieldValidation, type FormListParams, type FormSettings, type FormSubmission, type ListParams, type LoginCredentials, type Media, type Member, type Order, type OrderItem, type OrderListParams, type OrderStatus, type PaginatedResponse, type Payment, type PaymentCancelData, type PaymentConfirmData, type PaymentMethod, type PaymentReadyData, type PaymentStatus, type PostListParams, type Product, type ProductCategory, type ProductListParams, type ProductOption, type ProductOptionValue, type ProductStatus, type ProductVariant, Promptly, type PromptlyConfig, PromptlyError, type RegisterData, type ResetPasswordData, type SocialAuthUrl, type SocialProvider, type SubmissionListParams, type SubmitFormData, type UpdateCartItemData, type UpdateCommentData, type UpdateEntityRecordData, type UpdatePostData, type UpdateProfileData, Promptly as default };
+export { type AddToCartData, type ApiError, type ApiResponse, type ApplyCouponData, type AuthResponse, type BlogListParams, type BlogPost, type Board, type BoardComment, type BoardListParams, type BoardPost, type BoardSettings, type Cart, type CartItem, type Coupon, type CouponType, type CouponValidation, type CreateCommentData, type CreateEntityRecordData, type CreateOrderData, type CreatePostData, type CustomEntity, type EntityField, type EntityListParams, type EntityRecord, type EntitySchema, type ForgotPasswordData, type Form, type FormField, type FormFieldOption, type FormFieldType, type FormFieldValidation, type FormListParams, type FormSettings, type FormSubmission, type ListParams, type ListResponse, type LoginCredentials, type Media, type Member, type Order, type OrderItem, type OrderListParams, type OrderStatus, type PaginatedResponse, type PaginationMeta, type Payment, type PaymentCancelData, type PaymentConfirmData, type PaymentMethod, type PaymentReadyData, type PaymentStatus, type PostListParams, type Product, type ProductCategory, type ProductListParams, type ProductOption, type ProductOptionValue, type ProductStatus, type ProductVariant, Promptly, type PromptlyConfig, PromptlyError, type RegisterData, type ResetPasswordData, type SocialAuthUrl, type SocialProvider, type SubmissionListParams, type SubmitFormData, type UpdateCartItemData, type UpdateCommentData, type UpdateEntityRecordData, type UpdatePostData, type UpdateProfileData, Promptly as default };

package/dist/index.js

@@ -27,6 +27,38 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/http.ts
+var DEFAULT_META = {
+  current_page: 1,
+  last_page: 1,
+  per_page: 15,
+  total: 0,
+  from: null,
+  to: null
+};
+function normalizeListResponse(response) {
+  if (response == null) {
+    return { data: [], meta: { ...DEFAULT_META } };
+  }
+  if (Array.isArray(response)) {
+    return {
+      data: response,
+      meta: { ...DEFAULT_META, total: response.length, from: response.length > 0 ? 1 : null, to: response.length > 0 ? response.length : null }
+    };
+  }
+  if (typeof response === "object") {
+    const data = Array.isArray(response.data) ? response.data : [];
+    const meta = {
+      current_page: response.meta?.current_page ?? response.current_page ?? 1,
+      last_page: response.meta?.last_page ?? response.last_page ?? 1,
+      per_page: response.meta?.per_page ?? response.per_page ?? 15,
+      total: response.meta?.total ?? response.total ?? data.length,
+      from: response.meta?.from ?? response.from ?? (data.length > 0 ? 1 : null),
+      to: response.meta?.to ?? response.to ?? (data.length > 0 ? data.length : null)
+    };
+    return { data, meta };
+  }
+  return { data: [], meta: { ...DEFAULT_META } };
+}
 var PromptlyError = class extends Error {
   constructor(message, status, errors) {
     super(message);
@@ -134,6 +166,14 @@ var HttpClient = class {
   get(endpoint, params) {
     return this.request(endpoint, { method: "GET", params });
   }
+  /**
+   * GET request for list endpoints - ALWAYS returns normalized ListResponse
+   * Guarantees: data is always an array, meta is always present
+   */
+  async getList(endpoint, params) {
+    const response = await this.request(endpoint, { method: "GET", params });
+    return normalizeListResponse(response);
+  }
   /**
    * POST request
    */
@@ -317,9 +357,10 @@ var BoardsResource = class {
   // ============================================
   /**
    * List all boards
+   * @returns ListResponse with data array (always defined) and pagination meta
    */
   async list(params) {
-    return this.http.get("/public/boards", params);
+    return this.http.getList("/public/boards", params);
   }
   /**
    * Get board by ID or slug
@@ -332,9 +373,10 @@ var BoardsResource = class {
   // ============================================
   /**
    * List posts in a board
+   * @returns ListResponse with data array and pagination meta
    */
   async listPosts(boardIdOrSlug, params) {
-    return this.http.get(`/public/boards/${boardIdOrSlug}/posts`, params);
+    return this.http.getList(`/public/boards/${boardIdOrSlug}/posts`, params);
   }
   /**
    * Get post by ID
@@ -368,9 +410,11 @@ var BoardsResource = class {
   // ============================================
   /**
    * List comments for a post
+   * @returns Array of comments (always an array, never null/undefined)
    */
   async listComments(postId) {
-    return this.http.get(`/public/posts/${postId}/comments`);
+    const response = await this.http.getList(`/public/posts/${postId}/comments`);
+    return response.data;
   }
   /**
    * Create comment on a post
@@ -399,9 +443,10 @@ var BlogResource = class {
   }
   /**
    * List blog posts
+   * @returns ListResponse with data array (always defined) and pagination meta
    */
   async list(params) {
-    return this.http.get("/public/blog", params);
+    return this.http.getList("/public/blog", params);
   }
   /**
    * Get blog post by slug
@@ -417,9 +462,10 @@ var BlogResource = class {
   }
   /**
    * Get featured blog posts
+   * @returns Array of featured posts (always an array, never null/undefined)
    */
   async featured(limit = 5) {
-    const response = await this.http.get("/public/blog", {
+    const response = await this.http.getList("/public/blog", {
       per_page: limit,
       featured: true
     });
@@ -427,42 +473,49 @@ var BlogResource = class {
   }
   /**
    * Get blog posts by category
+   * @returns ListResponse with data array and pagination meta
    */
   async byCategory(category, params) {
-    return this.http.get("/public/blog", {
+    return this.http.getList("/public/blog", {
       ...params,
       category
     });
   }
   /**
    * Get blog posts by tag
+   * @returns ListResponse with data array and pagination meta
    */
   async byTag(tag, params) {
-    return this.http.get("/public/blog", {
+    return this.http.getList("/public/blog", {
       ...params,
       tag
     });
   }
   /**
    * Search blog posts
+   * @returns ListResponse with data array and pagination meta
    */
   async search(query, params) {
-    return this.http.get("/public/blog", {
+    return this.http.getList("/public/blog", {
       ...params,
       search: query
     });
   }
   /**
    * Get blog categories
+   * @returns Array of category names (always an array)
    */
   async categories() {
-    return this.http.get("/public/blog/categories");
+    const response = await this.http.get("/public/blog/categories");
+    return Array.isArray(response) ? response : response?.data ?? [];
   }
   /**
    * Get blog tags
+   * @returns Array of tag names (always an array)
    */
   async tags() {
-    return this.http.get("/public/blog/tags");
+    const response = await this.http.get("/public/blog/tags");
+    return Array.isArray(response) ? response : response?.data ?? [];
   }
 };
 
@@ -473,9 +526,10 @@ var FormsResource = class {
   }
   /**
    * List all forms
+   * @returns ListResponse with data array and pagination meta
    */
   async list(params) {
-    return this.http.get("/public/forms", params);
+    return this.http.getList("/public/forms", params);
   }
   /**
    * Get form by ID or slug
@@ -494,9 +548,10 @@ var FormsResource = class {
   // ============================================
   /**
    * Get my form submissions
+   * @returns ListResponse with data array and pagination meta
    */
   async mySubmissions(params) {
-    return this.http.get("/form-submissions", params);
+    return this.http.getList("/form-submissions", params);
   }
   /**
    * Get specific submission
@@ -516,9 +571,10 @@ var ShopResource = class {
   // ============================================
   /**
    * List products
+   * @returns ListResponse with data array and pagination meta
    */
   async listProducts(params) {
-    return this.http.get("/public/products", params);
+    return this.http.getList("/public/products", params);
   }
   /**
    * Get product by ID or slug
@@ -528,9 +584,10 @@ var ShopResource = class {
   }
   /**
    * Get featured products
+   * @returns Array of featured products (always an array)
    */
   async featuredProducts(limit = 8) {
-    const response = await this.http.get("/public/products", {
+    const response = await this.http.getList("/public/products", {
       per_page: limit,
       is_featured: true
     });
@@ -538,9 +595,10 @@ var ShopResource = class {
   }
   /**
    * Search products
+   * @returns ListResponse with data array and pagination meta
    */
   async searchProducts(query, params) {
-    return this.http.get("/public/products", {
+    return this.http.getList("/public/products", {
       ...params,
       search: query
     });
@@ -550,9 +608,11 @@ var ShopResource = class {
   // ============================================
   /**
    * List product categories
+   * @returns Array of categories (always an array)
    */
   async listCategories() {
-    return this.http.get("/public/categories");
+    const response = await this.http.getList("/public/categories");
+    return response.data;
   }
   /**
    * Get category by ID or slug
@@ -562,9 +622,10 @@ var ShopResource = class {
   }
   /**
    * Get products in category
+   * @returns ListResponse with data array and pagination meta
    */
   async categoryProducts(categoryIdOrSlug, params) {
-    return this.http.get(`/public/categories/${categoryIdOrSlug}/products`, params);
+    return this.http.getList(`/public/categories/${categoryIdOrSlug}/products`, params);
   }
   // ============================================
   // Cart
@@ -604,9 +665,10 @@ var ShopResource = class {
   // ============================================
   /**
    * List my orders
+   * @returns ListResponse with data array and pagination meta
    */
   async listOrders(params) {
-    return this.http.get("/orders", params);
+    return this.http.getList("/orders", params);
   }
   /**
    * Get order by ID or order number
@@ -667,9 +729,11 @@ var ShopResource = class {
   }
   /**
    * Get available coupons for current user
+   * @returns Array of coupons (always an array)
    */
   async myCoupons() {
-    return this.http.get("/coupons");
+    const response = await this.http.getList("/coupons");
+    return response.data;
   }
 };
 
@@ -725,6 +789,7 @@ var EntitiesResource = class {
   // ============================================
   /**
    * List all active custom entities
+   * @returns Array of entities (always an array)
    *
    * @example
    * ```typescript
@@ -733,7 +798,8 @@ var EntitiesResource = class {
    * ```
    */
   async list() {
-    return this.http.get("/public/entities");
+    const response = await this.http.getList("/public/entities");
+    return response.data;
   }
   /**
    * Get entity schema by slug
@@ -752,6 +818,7 @@ var EntitiesResource = class {
   // ============================================
   /**
    * List records for an entity
+   * @returns ListResponse with data array and pagination meta
    *
    * @example
    * ```typescript
@@ -772,7 +839,7 @@ var EntitiesResource = class {
    * ```
    */
   async listRecords(slug, params) {
-    return this.http.get(`/public/entities/${slug}`, params);
+    return this.http.getList(`/public/entities/${slug}`, params);
   }
   /**
    * Get a single record by ID

package/dist/index.mjs

@@ -1,4 +1,36 @@
 // src/http.ts
+var DEFAULT_META = {
+  current_page: 1,
+  last_page: 1,
+  per_page: 15,
+  total: 0,
+  from: null,
+  to: null
+};
+function normalizeListResponse(response) {
+  if (response == null) {
+    return { data: [], meta: { ...DEFAULT_META } };
+  }
+  if (Array.isArray(response)) {
+    return {
+      data: response,
+      meta: { ...DEFAULT_META, total: response.length, from: response.length > 0 ? 1 : null, to: response.length > 0 ? response.length : null }
+    };
+  }
+  if (typeof response === "object") {
+    const data = Array.isArray(response.data) ? response.data : [];
+    const meta = {
+      current_page: response.meta?.current_page ?? response.current_page ?? 1,
+      last_page: response.meta?.last_page ?? response.last_page ?? 1,
+      per_page: response.meta?.per_page ?? response.per_page ?? 15,
+      total: response.meta?.total ?? response.total ?? data.length,
+      from: response.meta?.from ?? response.from ?? (data.length > 0 ? 1 : null),
+      to: response.meta?.to ?? response.to ?? (data.length > 0 ? data.length : null)
+    };
+    return { data, meta };
+  }
+  return { data: [], meta: { ...DEFAULT_META } };
+}
 var PromptlyError = class extends Error {
   constructor(message, status, errors) {
     super(message);
@@ -106,6 +138,14 @@ var HttpClient = class {
   get(endpoint, params) {
     return this.request(endpoint, { method: "GET", params });
   }
+  /**
+   * GET request for list endpoints - ALWAYS returns normalized ListResponse
+   * Guarantees: data is always an array, meta is always present
+   */
+  async getList(endpoint, params) {
+    const response = await this.request(endpoint, { method: "GET", params });
+    return normalizeListResponse(response);
+  }
   /**
    * POST request
    */
@@ -289,9 +329,10 @@ var BoardsResource = class {
   // ============================================
   /**
    * List all boards
+   * @returns ListResponse with data array (always defined) and pagination meta
    */
   async list(params) {
-    return this.http.get("/public/boards", params);
+    return this.http.getList("/public/boards", params);
   }
   /**
    * Get board by ID or slug
@@ -304,9 +345,10 @@ var BoardsResource = class {
   // ============================================
   /**
    * List posts in a board
+   * @returns ListResponse with data array and pagination meta
    */
   async listPosts(boardIdOrSlug, params) {
-    return this.http.get(`/public/boards/${boardIdOrSlug}/posts`, params);
+    return this.http.getList(`/public/boards/${boardIdOrSlug}/posts`, params);
   }
   /**
    * Get post by ID
@@ -340,9 +382,11 @@ var BoardsResource = class {
   // ============================================
   /**
    * List comments for a post
+   * @returns Array of comments (always an array, never null/undefined)
    */
   async listComments(postId) {
-    return this.http.get(`/public/posts/${postId}/comments`);
+    const response = await this.http.getList(`/public/posts/${postId}/comments`);
+    return response.data;
   }
   /**
    * Create comment on a post
@@ -371,9 +415,10 @@ var BlogResource = class {
   }
   /**
    * List blog posts
+   * @returns ListResponse with data array (always defined) and pagination meta
    */
   async list(params) {
-    return this.http.get("/public/blog", params);
+    return this.http.getList("/public/blog", params);
   }
   /**
    * Get blog post by slug
@@ -389,9 +434,10 @@ var BlogResource = class {
   }
   /**
    * Get featured blog posts
+   * @returns Array of featured posts (always an array, never null/undefined)
    */
   async featured(limit = 5) {
-    const response = await this.http.get("/public/blog", {
+    const response = await this.http.getList("/public/blog", {
       per_page: limit,
       featured: true
     });
@@ -399,42 +445,49 @@ var BlogResource = class {
   }
   /**
    * Get blog posts by category
+   * @returns ListResponse with data array and pagination meta
    */
   async byCategory(category, params) {
-    return this.http.get("/public/blog", {
+    return this.http.getList("/public/blog", {
       ...params,
       category
     });
   }
   /**
    * Get blog posts by tag
+   * @returns ListResponse with data array and pagination meta
    */
   async byTag(tag, params) {
-    return this.http.get("/public/blog", {
+    return this.http.getList("/public/blog", {
       ...params,
       tag
     });
   }
   /**
    * Search blog posts
+   * @returns ListResponse with data array and pagination meta
    */
   async search(query, params) {
-    return this.http.get("/public/blog", {
+    return this.http.getList("/public/blog", {
       ...params,
       search: query
     });
   }
   /**
    * Get blog categories
+   * @returns Array of category names (always an array)
    */
   async categories() {
-    return this.http.get("/public/blog/categories");
+    const response = await this.http.get("/public/blog/categories");
+    return Array.isArray(response) ? response : response?.data ?? [];
   }
   /**
    * Get blog tags
+   * @returns Array of tag names (always an array)
    */
   async tags() {
-    return this.http.get("/public/blog/tags");
+    const response = await this.http.get("/public/blog/tags");
+    return Array.isArray(response) ? response : response?.data ?? [];
   }
 };
 
@@ -445,9 +498,10 @@ var FormsResource = class {
   }
   /**
    * List all forms
+   * @returns ListResponse with data array and pagination meta
    */
   async list(params) {
-    return this.http.get("/public/forms", params);
+    return this.http.getList("/public/forms", params);
   }
   /**
    * Get form by ID or slug
@@ -466,9 +520,10 @@ var FormsResource = class {
   // ============================================
   /**
    * Get my form submissions
+   * @returns ListResponse with data array and pagination meta
    */
   async mySubmissions(params) {
-    return this.http.get("/form-submissions", params);
+    return this.http.getList("/form-submissions", params);
   }
   /**
    * Get specific submission
@@ -488,9 +543,10 @@ var ShopResource = class {
   // ============================================
   /**
    * List products
+   * @returns ListResponse with data array and pagination meta
    */
   async listProducts(params) {
-    return this.http.get("/public/products", params);
+    return this.http.getList("/public/products", params);
   }
   /**
    * Get product by ID or slug
@@ -500,9 +556,10 @@ var ShopResource = class {
   }
   /**
    * Get featured products
+   * @returns Array of featured products (always an array)
    */
   async featuredProducts(limit = 8) {
-    const response = await this.http.get("/public/products", {
+    const response = await this.http.getList("/public/products", {
       per_page: limit,
       is_featured: true
     });
@@ -510,9 +567,10 @@ var ShopResource = class {
   }
   /**
    * Search products
+   * @returns ListResponse with data array and pagination meta
    */
   async searchProducts(query, params) {
-    return this.http.get("/public/products", {
+    return this.http.getList("/public/products", {
       ...params,
       search: query
     });
@@ -522,9 +580,11 @@ var ShopResource = class {
   // ============================================
   /**
    * List product categories
+   * @returns Array of categories (always an array)
    */
   async listCategories() {
-    return this.http.get("/public/categories");
+    const response = await this.http.getList("/public/categories");
+    return response.data;
   }
   /**
    * Get category by ID or slug
@@ -534,9 +594,10 @@ var ShopResource = class {
   }
   /**
    * Get products in category
+   * @returns ListResponse with data array and pagination meta
    */
   async categoryProducts(categoryIdOrSlug, params) {
-    return this.http.get(`/public/categories/${categoryIdOrSlug}/products`, params);
+    return this.http.getList(`/public/categories/${categoryIdOrSlug}/products`, params);
   }
   // ============================================
   // Cart
@@ -576,9 +637,10 @@ var ShopResource = class {
   // ============================================
   /**
    * List my orders
+   * @returns ListResponse with data array and pagination meta
    */
   async listOrders(params) {
-    return this.http.get("/orders", params);
+    return this.http.getList("/orders", params);
   }
   /**
    * Get order by ID or order number
@@ -639,9 +701,11 @@ var ShopResource = class {
   }
   /**
    * Get available coupons for current user
+   * @returns Array of coupons (always an array)
    */
   async myCoupons() {
-    return this.http.get("/coupons");
+    const response = await this.http.getList("/coupons");
+    return response.data;
   }
 };
 
@@ -697,6 +761,7 @@ var EntitiesResource = class {
   // ============================================
   /**
    * List all active custom entities
+   * @returns Array of entities (always an array)
    *
    * @example
    * ```typescript
@@ -705,7 +770,8 @@ var EntitiesResource = class {
    * ```
    */
   async list() {
-    return this.http.get("/public/entities");
+    const response = await this.http.getList("/public/entities");
+    return response.data;
   }
   /**
    * Get entity schema by slug
@@ -724,6 +790,7 @@ var EntitiesResource = class {
   // ============================================
   /**
    * List records for an entity
+   * @returns ListResponse with data array and pagination meta
    *
    * @example
    * ```typescript
@@ -744,7 +811,7 @@ var EntitiesResource = class {
    * ```
    */
   async listRecords(slug, params) {
-    return this.http.get(`/public/entities/${slug}`, params);
+    return this.http.getList(`/public/entities/${slug}`, params);
   }
   /**
    * Get a single record by ID

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@back23/promptly-sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Promptly AI CMS SDK for JavaScript/TypeScript",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -32,7 +32,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/kingofecommerce/promptly-sdk.git"
+    "url": "https://github.com/kingofecommerce/back23-promptly-sdk.git"
   },
     "devDependencies": {
     "tsup": "^8.0.0",