laravel-query-gate-sdk 1.0.0 → 1.0.1

package/README.md

@@ -221,8 +221,6 @@ const posts = await queryGate<PostContract>('posts')
   .filter('status', 'eq', 'published')
   .filter('author_id', 'eq', 1)
   .sort('created_at', 'desc')
-  .page(1)
-  .perPage(10)
   .get()
 ```
 
@@ -358,11 +356,56 @@ queryGate<PostContract>('posts')
 
 ### Pagination
 
+The SDK supports both Laravel pagination methods. The backend controls items per page.
+
+#### Standard Pagination (Laravel `paginate()`)
+
 ```typescript
-queryGate<PostContract>('posts')
-  .page(2)
-  .perPage(25)
-  .get()
+import type { PaginateResponse } from 'laravel-query-gate-sdk'
+
+// First page
+const posts = await queryGate<PostContract>('posts')
+  .paginate()
+  .get() as PaginateResponse<Post>
+
+// Specific page
+const page2 = await queryGate<PostContract>('posts')
+  .paginate(2)
+  .get() as PaginateResponse<Post>
+
+// Response includes: current_page, data, first_page_url, last_page, total, etc.
+console.log(posts.data)         // Post[]
+console.log(posts.current_page) // 1
+console.log(posts.last_page)    // 10
+console.log(posts.total)        // 100
+```
+
+#### Cursor Pagination (Laravel `cursorPaginate()`)
+
+```typescript
+import type { CursorPaginateResponse } from 'laravel-query-gate-sdk'
+
+// First page
+const posts = await queryGate<PostContract>('posts')
+  .cursor()
+  .get() as CursorPaginateResponse<Post>
+
+// Next page using cursor from previous response
+const nextPage = await queryGate<PostContract>('posts')
+  .cursor(posts.next_cursor)
+  .get() as CursorPaginateResponse<Post>
+
+// Response includes: data, next_cursor, prev_cursor, next_page_url, prev_page_url
+console.log(posts.data)        // Post[]
+console.log(posts.next_cursor) // "eyJjcmVhdGVkX2F0Ijoi..."
+```
+
+#### No Pagination (Fetch All)
+
+```typescript
+// Without .paginate() or .cursor(), fetches all records
+const allPosts = await queryGate<PostContract>('posts').get()
+// allPosts: Post[]
 ```
 
 ## Versioning
@@ -628,8 +671,8 @@ Create an isolated SDK instance with its own configuration.
 | `.id(id)` | Set resource ID for single resource operations |
 | `.filter(field, operator, value)` | Add a filter |
 | `.sort(field, direction?)` | Add sorting (default: 'asc') |
-| `.page(page)` | Set page number |
-| `.perPage(count)` | Set items per page |
+| `.paginate(page?)` | Use standard pagination (Laravel `paginate()`) |
+| `.cursor(cursor?)` | Use cursor pagination (Laravel `cursorPaginate()`) |
 | `.version(version)` | Set API version header |
 | `.header(key, value)` | Add a single header |
 | `.headers(record)` | Add multiple headers |
@@ -659,6 +702,9 @@ import type {
   SortDirection,
   QueryGateConfig,
   ValidationErrors,
+  // Pagination response types
+  PaginateResponse,
+  CursorPaginateResponse,
 } from 'laravel-query-gate-sdk'
 ```
 

package/dist/index.d.mts

@@ -48,6 +48,62 @@ interface RequestConfig {
     headers: Record<string, string>;
     fetchOptions: RequestInit;
 }
+/**
+ * Pagination type
+ */
+type PaginationType = 'paginate' | 'cursor';
+/**
+ * Paginate pagination state (Laravel paginate())
+ */
+interface PaginatePaginationState {
+    type: 'paginate';
+    page?: number;
+}
+/**
+ * Cursor pagination state (Laravel cursorPaginate())
+ */
+interface CursorPaginationState {
+    type: 'cursor';
+    cursor?: string | null;
+}
+/**
+ * Union of pagination states
+ */
+type PaginationState = PaginatePaginationState | CursorPaginationState | null;
+/**
+ * Laravel paginate response shape
+ */
+interface PaginateResponse<T> {
+    current_page: number;
+    data: T[];
+    first_page_url: string;
+    from: number | null;
+    last_page: number;
+    last_page_url: string;
+    links: Array<{
+        url: string | null;
+        label: string;
+        active: boolean;
+    }>;
+    next_page_url: string | null;
+    path: string;
+    per_page: number;
+    prev_page_url: string | null;
+    to: number | null;
+    total: number;
+}
+/**
+ * Laravel cursor paginate response shape
+ */
+interface CursorPaginateResponse<T> {
+    data: T[];
+    path: string;
+    per_page: number;
+    next_cursor: string | null;
+    next_page_url: string | null;
+    prev_cursor: string | null;
+    prev_page_url: string | null;
+}
 /**
  * Internal request state
  */
@@ -56,10 +112,7 @@ interface RequestState {
     id?: string | number;
     filters: FilterDefinition[];
     sorts: SortDefinition[];
-    pagination: {
-        page?: number;
-        perPage?: number;
-    };
+    pagination: PaginationState;
     version?: string;
     action?: string;
     headers: Record<string, string>;
@@ -199,13 +252,15 @@ declare class QueryGateBuilder<TContract extends ResourceContract> {
      */
     sort(field: string, direction?: SortDirection): QueryGateBuilder<TContract>;
     /**
-     * Set pagination page
+     * Set standard pagination (Laravel paginate())
+     * @param page - Page number (optional)
      */
-    page(page: number): QueryGateBuilder<TContract>;
+    paginate(page?: number): QueryGateBuilder<TContract>;
     /**
-     * Set items per page
+     * Set cursor pagination (Laravel cursorPaginate())
+     * @param cursor - Cursor string (optional, null for first page)
      */
-    perPage(perPage: number): QueryGateBuilder<TContract>;
+    cursor(cursor?: string | null): QueryGateBuilder<TContract>;
     /**
      * Set API version header
      */
@@ -490,4 +545,4 @@ declare function isServerError(error: unknown): error is QueryGateServerError;
  */
 declare function isServiceUnavailableError(error: unknown): error is QueryGateServiceUnavailableError;
 
-export { ActionBuilderNoPayload, ActionBuilderWithPayload, type ActionContract, type FilterDefinition, type FilterOperator, QueryGateBuilder, QueryGateBuilderWithId, type QueryGateConfig, QueryGateCsrfMismatchError, QueryGateError, QueryGateForbiddenError, QueryGateHttpError, QueryGateNetworkError, QueryGateNotFoundError, QueryGateRateLimitError, QueryGateServerError, QueryGateServiceUnavailableError, QueryGateUnauthorizedError, QueryGateValidationError, type RequestConfig, type RequestState, type ResourceContract, type SortDefinition, type SortDirection, type ValidationErrors, configureQueryGate, createQueryGate, getQueryGateConfig, isCsrfMismatchError, isForbiddenError, isHttpError, isNetworkError, isNotFoundError, isQueryGateError, isRateLimitError, isServerError, isServiceUnavailableError, isUnauthorizedError, isValidationError, queryGate, resetQueryGateConfig };
+export { ActionBuilderNoPayload, ActionBuilderWithPayload, type ActionContract, type CursorPaginateResponse, type CursorPaginationState, type FilterDefinition, type FilterOperator, type PaginatePaginationState, type PaginateResponse, type PaginationState, type PaginationType, QueryGateBuilder, QueryGateBuilderWithId, type QueryGateConfig, QueryGateCsrfMismatchError, QueryGateError, QueryGateForbiddenError, QueryGateHttpError, QueryGateNetworkError, QueryGateNotFoundError, QueryGateRateLimitError, QueryGateServerError, QueryGateServiceUnavailableError, QueryGateUnauthorizedError, QueryGateValidationError, type RequestConfig, type RequestState, type ResourceContract, type SortDefinition, type SortDirection, type ValidationErrors, configureQueryGate, createQueryGate, getQueryGateConfig, isCsrfMismatchError, isForbiddenError, isHttpError, isNetworkError, isNotFoundError, isQueryGateError, isRateLimitError, isServerError, isServiceUnavailableError, isUnauthorizedError, isValidationError, queryGate, resetQueryGateConfig };

package/dist/index.d.ts

@@ -48,6 +48,62 @@ interface RequestConfig {
     headers: Record<string, string>;
     fetchOptions: RequestInit;
 }
+/**
+ * Pagination type
+ */
+type PaginationType = 'paginate' | 'cursor';
+/**
+ * Paginate pagination state (Laravel paginate())
+ */
+interface PaginatePaginationState {
+    type: 'paginate';
+    page?: number;
+}
+/**
+ * Cursor pagination state (Laravel cursorPaginate())
+ */
+interface CursorPaginationState {
+    type: 'cursor';
+    cursor?: string | null;
+}
+/**
+ * Union of pagination states
+ */
+type PaginationState = PaginatePaginationState | CursorPaginationState | null;
+/**
+ * Laravel paginate response shape
+ */
+interface PaginateResponse<T> {
+    current_page: number;
+    data: T[];
+    first_page_url: string;
+    from: number | null;
+    last_page: number;
+    last_page_url: string;
+    links: Array<{
+        url: string | null;
+        label: string;
+        active: boolean;
+    }>;
+    next_page_url: string | null;
+    path: string;
+    per_page: number;
+    prev_page_url: string | null;
+    to: number | null;
+    total: number;
+}
+/**
+ * Laravel cursor paginate response shape
+ */
+interface CursorPaginateResponse<T> {
+    data: T[];
+    path: string;
+    per_page: number;
+    next_cursor: string | null;
+    next_page_url: string | null;
+    prev_cursor: string | null;
+    prev_page_url: string | null;
+}
 /**
  * Internal request state
  */
@@ -56,10 +112,7 @@ interface RequestState {
     id?: string | number;
     filters: FilterDefinition[];
     sorts: SortDefinition[];
-    pagination: {
-        page?: number;
-        perPage?: number;
-    };
+    pagination: PaginationState;
     version?: string;
     action?: string;
     headers: Record<string, string>;
@@ -199,13 +252,15 @@ declare class QueryGateBuilder<TContract extends ResourceContract> {
      */
     sort(field: string, direction?: SortDirection): QueryGateBuilder<TContract>;
     /**
-     * Set pagination page
+     * Set standard pagination (Laravel paginate())
+     * @param page - Page number (optional)
      */
-    page(page: number): QueryGateBuilder<TContract>;
+    paginate(page?: number): QueryGateBuilder<TContract>;
     /**
-     * Set items per page
+     * Set cursor pagination (Laravel cursorPaginate())
+     * @param cursor - Cursor string (optional, null for first page)
      */
-    perPage(perPage: number): QueryGateBuilder<TContract>;
+    cursor(cursor?: string | null): QueryGateBuilder<TContract>;
     /**
      * Set API version header
      */
@@ -490,4 +545,4 @@ declare function isServerError(error: unknown): error is QueryGateServerError;
  */
 declare function isServiceUnavailableError(error: unknown): error is QueryGateServiceUnavailableError;
 
-export { ActionBuilderNoPayload, ActionBuilderWithPayload, type ActionContract, type FilterDefinition, type FilterOperator, QueryGateBuilder, QueryGateBuilderWithId, type QueryGateConfig, QueryGateCsrfMismatchError, QueryGateError, QueryGateForbiddenError, QueryGateHttpError, QueryGateNetworkError, QueryGateNotFoundError, QueryGateRateLimitError, QueryGateServerError, QueryGateServiceUnavailableError, QueryGateUnauthorizedError, QueryGateValidationError, type RequestConfig, type RequestState, type ResourceContract, type SortDefinition, type SortDirection, type ValidationErrors, configureQueryGate, createQueryGate, getQueryGateConfig, isCsrfMismatchError, isForbiddenError, isHttpError, isNetworkError, isNotFoundError, isQueryGateError, isRateLimitError, isServerError, isServiceUnavailableError, isUnauthorizedError, isValidationError, queryGate, resetQueryGateConfig };
+export { ActionBuilderNoPayload, ActionBuilderWithPayload, type ActionContract, type CursorPaginateResponse, type CursorPaginationState, type FilterDefinition, type FilterOperator, type PaginatePaginationState, type PaginateResponse, type PaginationState, type PaginationType, QueryGateBuilder, QueryGateBuilderWithId, type QueryGateConfig, QueryGateCsrfMismatchError, QueryGateError, QueryGateForbiddenError, QueryGateHttpError, QueryGateNetworkError, QueryGateNotFoundError, QueryGateRateLimitError, QueryGateServerError, QueryGateServiceUnavailableError, QueryGateUnauthorizedError, QueryGateValidationError, type RequestConfig, type RequestState, type ResourceContract, type SortDefinition, type SortDirection, type ValidationErrors, configureQueryGate, createQueryGate, getQueryGateConfig, isCsrfMismatchError, isForbiddenError, isHttpError, isNetworkError, isNotFoundError, isQueryGateError, isRateLimitError, isServerError, isServiceUnavailableError, isUnauthorizedError, isValidationError, queryGate, resetQueryGateConfig };

package/dist/index.js

@@ -248,11 +248,16 @@ function buildUrl(config, state) {
     const sortValue = state.sorts.map((s) => `${s.field}:${s.direction}`).join(",");
     params.append("sort", sortValue);
   }
-  if (state.pagination.page !== void 0) {
-    params.append("page", String(state.pagination.page));
-  }
-  if (state.pagination.perPage !== void 0) {
-    params.append("per_page", String(state.pagination.perPage));
+  if (state.pagination) {
+    if (state.pagination.type === "paginate") {
+      if (state.pagination.page !== void 0) {
+        params.append("page", String(state.pagination.page));
+      }
+    } else if (state.pagination.type === "cursor") {
+      if (state.pagination.cursor !== void 0 && state.pagination.cursor !== null) {
+        params.append("cursor", state.pagination.cursor);
+      }
+    }
   }
   const queryString = params.toString();
   return queryString ? `${baseUrl}${path}?${queryString}` : `${baseUrl}${path}`;
@@ -359,7 +364,7 @@ function createInitialState(resource) {
     resource,
     filters: [],
     sorts: [],
-    pagination: {},
+    pagination: null,
     headers: {},
     fetchOptions: {}
   };
@@ -369,7 +374,7 @@ function cloneState(state) {
     ...state,
     filters: [...state.filters],
     sorts: [...state.sorts],
-    pagination: { ...state.pagination },
+    pagination: state.pagination ? { ...state.pagination } : null,
     headers: { ...state.headers },
     fetchOptions: { ...state.fetchOptions }
   };
@@ -570,19 +575,33 @@ var QueryGateBuilder = class _QueryGateBuilder {
     return new _QueryGateBuilder(this.config, newState);
   }
   /**
-   * Set pagination page
+   * Set standard pagination (Laravel paginate())
+   * @param page - Page number (optional)
    */
-  page(page) {
+  paginate(page) {
     const newState = cloneState(this.state);
-    newState.pagination.page = page;
+    const paginationState = {
+      type: "paginate"
+    };
+    if (page !== void 0) {
+      paginationState.page = page;
+    }
+    newState.pagination = paginationState;
     return new _QueryGateBuilder(this.config, newState);
   }
   /**
-   * Set items per page
+   * Set cursor pagination (Laravel cursorPaginate())
+   * @param cursor - Cursor string (optional, null for first page)
    */
-  perPage(perPage) {
+  cursor(cursor) {
     const newState = cloneState(this.state);
-    newState.pagination.perPage = perPage;
+    const paginationState = {
+      type: "cursor"
+    };
+    if (cursor !== void 0) {
+      paginationState.cursor = cursor;
+    }
+    newState.pagination = paginationState;
     return new _QueryGateBuilder(this.config, newState);
   }
   /**

package/dist/index.mjs

@@ -192,11 +192,16 @@ function buildUrl(config, state) {
     const sortValue = state.sorts.map((s) => `${s.field}:${s.direction}`).join(",");
     params.append("sort", sortValue);
   }
-  if (state.pagination.page !== void 0) {
-    params.append("page", String(state.pagination.page));
-  }
-  if (state.pagination.perPage !== void 0) {
-    params.append("per_page", String(state.pagination.perPage));
+  if (state.pagination) {
+    if (state.pagination.type === "paginate") {
+      if (state.pagination.page !== void 0) {
+        params.append("page", String(state.pagination.page));
+      }
+    } else if (state.pagination.type === "cursor") {
+      if (state.pagination.cursor !== void 0 && state.pagination.cursor !== null) {
+        params.append("cursor", state.pagination.cursor);
+      }
+    }
   }
   const queryString = params.toString();
   return queryString ? `${baseUrl}${path}?${queryString}` : `${baseUrl}${path}`;
@@ -303,7 +308,7 @@ function createInitialState(resource) {
     resource,
     filters: [],
     sorts: [],
-    pagination: {},
+    pagination: null,
     headers: {},
     fetchOptions: {}
   };
@@ -313,7 +318,7 @@ function cloneState(state) {
     ...state,
     filters: [...state.filters],
     sorts: [...state.sorts],
-    pagination: { ...state.pagination },
+    pagination: state.pagination ? { ...state.pagination } : null,
     headers: { ...state.headers },
     fetchOptions: { ...state.fetchOptions }
   };
@@ -514,19 +519,33 @@ var QueryGateBuilder = class _QueryGateBuilder {
     return new _QueryGateBuilder(this.config, newState);
   }
   /**
-   * Set pagination page
+   * Set standard pagination (Laravel paginate())
+   * @param page - Page number (optional)
    */
-  page(page) {
+  paginate(page) {
     const newState = cloneState(this.state);
-    newState.pagination.page = page;
+    const paginationState = {
+      type: "paginate"
+    };
+    if (page !== void 0) {
+      paginationState.page = page;
+    }
+    newState.pagination = paginationState;
     return new _QueryGateBuilder(this.config, newState);
   }
   /**
-   * Set items per page
+   * Set cursor pagination (Laravel cursorPaginate())
+   * @param cursor - Cursor string (optional, null for first page)
    */
-  perPage(perPage) {
+  cursor(cursor) {
     const newState = cloneState(this.state);
-    newState.pagination.perPage = perPage;
+    const paginationState = {
+      type: "cursor"
+    };
+    if (cursor !== void 0) {
+      paginationState.cursor = cursor;
+    }
+    newState.pagination = paginationState;
     return new _QueryGateBuilder(this.config, newState);
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "laravel-query-gate-sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Contract-driven TypeScript SDK for Laravel Query Gate",
   "main": "dist/index.js",
   "module": "dist/index.mjs",