laravel-query-gate-sdk 1.0.0 → 1.0.2

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,62 @@ 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 (with filters)
+const posts = await queryGate<PostContract>('posts')
+  .filter('status', 'eq', 'published')
+  .sort('created_at', 'desc')
+  .cursor()
+  .get() as CursorPaginateResponse<Post>
+// URL: /posts?filter[status][eq]=published&sort=created_at:desc
+
+// Next page - only cursor is sent (filters are encoded in the cursor)
+const nextPage = await queryGate<PostContract>('posts')
+  .cursor(posts.next_cursor)
+  .get() as CursorPaginateResponse<Post>
+// URL: /posts?cursor=eyJjcmVhdGVkX2F0Ijoi...
+
+// Response includes: data, next_cursor, prev_cursor, next_page_url, prev_page_url
+console.log(posts.data)        // Post[]
+console.log(posts.next_cursor) // "eyJjcmVhdGVkX2F0Ijoi..."
+```
+
+> **Note:** When navigating with a cursor, filters and sorts are not sent in the URL because Laravel's cursor already contains all query parameters encoded in base64.
+
+#### No Pagination (Fetch All)
+
+```typescript
+// Without .paginate() or .cursor(), fetches all records
+const allPosts = await queryGate<PostContract>('posts').get()
+// allPosts: Post[]
 ```
 
 ## Versioning
@@ -628,8 +677,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 +708,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

@@ -241,6 +241,12 @@ function buildUrl(config, state) {
     path += `/${state.action}`;
   }
   const params = new URLSearchParams();
+  const isCursorNavigation = state.pagination?.type === "cursor" && state.pagination.cursor !== void 0 && state.pagination.cursor !== null;
+  if (isCursorNavigation) {
+    params.append("cursor", state.pagination.cursor);
+    const queryString2 = params.toString();
+    return `${baseUrl}${path}?${queryString2}`;
+  }
   for (const filter of state.filters) {
     params.append(`filter[${filter.field}][${filter.operator}]`, String(filter.value));
   }
@@ -248,11 +254,12 @@ 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));
+      }
+    }
   }
   const queryString = params.toString();
   return queryString ? `${baseUrl}${path}?${queryString}` : `${baseUrl}${path}`;
@@ -359,7 +366,7 @@ function createInitialState(resource) {
     resource,
     filters: [],
     sorts: [],
-    pagination: {},
+    pagination: null,
     headers: {},
     fetchOptions: {}
   };
@@ -369,7 +376,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 +577,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

@@ -185,6 +185,12 @@ function buildUrl(config, state) {
     path += `/${state.action}`;
   }
   const params = new URLSearchParams();
+  const isCursorNavigation = state.pagination?.type === "cursor" && state.pagination.cursor !== void 0 && state.pagination.cursor !== null;
+  if (isCursorNavigation) {
+    params.append("cursor", state.pagination.cursor);
+    const queryString2 = params.toString();
+    return `${baseUrl}${path}?${queryString2}`;
+  }
   for (const filter of state.filters) {
     params.append(`filter[${filter.field}][${filter.operator}]`, String(filter.value));
   }
@@ -192,11 +198,12 @@ 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));
+      }
+    }
   }
   const queryString = params.toString();
   return queryString ? `${baseUrl}${path}?${queryString}` : `${baseUrl}${path}`;
@@ -303,7 +310,7 @@ function createInitialState(resource) {
     resource,
     filters: [],
     sorts: [],
-    pagination: {},
+    pagination: null,
     headers: {},
     fetchOptions: {}
   };
@@ -313,7 +320,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 +521,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.2",
   "description": "Contract-driven TypeScript SDK for Laravel Query Gate",
   "main": "dist/index.js",
   "module": "dist/index.mjs",