// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. import { APIResource } from '../../../core/resource'; import * as CapabilitiesAPI from './capabilities'; import { Capabilities as CapabilitiesAPICapabilities, CapabilityRetrieveResponse } from './capabilities'; import * as DefaultAPI from './default'; import { Default, DefaultUpdateParams, DefaultUpdateResponse } from './default'; import { APIPromise } from '../../../core/api-promise'; import { PageCursorURL, PagePromise } from '../../../core/pagination'; import { buildHeaders } from '../../../internal/headers'; import { RequestOptions } from '../../../internal/request-options'; import { path } from '../../../internal/utils/path'; /** * Saved custom object list views visible to the requester */ export class ListViews extends APIResource { capabilities: CapabilitiesAPI.Capabilities = new CapabilitiesAPI.Capabilities(this._client); default: DefaultAPI.Default = new DefaultAPI.Default(this._client); /** * Lists shared views and the requester's private views. Saved views do not grant * access to records or filter fields. * * @example SDK usage * ```ts * // Automatically fetches more pages as needed. * for await (const listViewListResponse of client.customObjects.listViews.list( * 'custom_object_api_name', * )) { * // ... * } * ``` * * @example HTTP * Representative request and response shapes. * ``` * GET /custom-objects/{custom_object_api_name}/list-views/?limit=50&cursor=cursor HTTP/1.1 * Host: rest.ripplingapis.com * Accept: application/json * Rippling-Api-Version: 2024-08-01 * * HTTP/1.1 200 OK * Content-Type: application/json * * { * "results": [ * { * "id": "string", * "created_at": "2025-01-01T00:00:00Z", * "updated_at": "2025-01-01T00:00:00Z", * "api_name": "string", * "name": "string", * "description": "string", * "visibility": "PRIVATE", * "record_scope": "ALL", * "has_filter": false, * "order_by": "string", * "columns": [ * {} * ], * "is_default": false, * "capabilities": { * "can_update": "string", * "can_delete": "string", * "can_duplicate": "string", * "can_share": "string", * "can_set_default": "string" * } * } * ], * "next_link": "string" * } * ``` */ list( customObjectAPIName: string, query: ListViewListParams | null | undefined = {}, options?: RequestOptions, ): PagePromise { return this._client.getAPIList( path`/custom-objects/${customObjectAPIName}/list-views/`, PageCursorURL, { query, ...options }, ); } /** * Creates a grid definition using ordered field API names, RQL, sorting, * visibility, and record scope. This does not change records or the company * default. Supply api_name for a stable retry identity: an existing active company * name returns 409, so retrieve it before retrying. Omitting api_name generates a * new name and retrying may create another view. An authorized caller can delete * the view. Uses existing Custom Object read consent. Native permissions require * ownership for private views and manage-object access for shared views, sharing, * and company defaults. Object-read consent does not authorize schema or record * writes. * * @example SDK usage * ```ts * const listView = * await client.customObjects.listViews.create( * 'custom_object_api_name', * { columns: [{ field: 'field' }], name: 'name' }, * ); * ``` * * @example HTTP * Representative request and response shapes. * ``` * POST /custom-objects/{custom_object_api_name}/list-views/ HTTP/1.1 * Host: rest.ripplingapis.com * Content-Type: application/json * Accept: application/json * Rippling-Api-Version: 2024-08-01 * * { * "columns": [ * { * "field": "field" * } * ], * "name": "name" * } * * HTTP/1.1 201 Created * Content-Type: application/json * * { * "id": "string", * "created_at": "2025-01-01T00:00:00Z", * "updated_at": "2025-01-01T00:00:00Z", * "api_name": "string", * "name": "string", * "description": "string", * "visibility": "PRIVATE", * "record_scope": "ALL", * "has_filter": false, * "order_by": "string", * "columns": [ * { * "field": "string" * } * ], * "is_default": false, * "capabilities": { * "can_update": false, * "can_delete": false, * "can_duplicate": false, * "can_share": false, * "can_set_default": false * }, * "query": "string" * } * ``` */ create( customObjectAPIName: string, body: ListViewCreateParams, options?: RequestOptions, ): APIPromise { return this._client.post(path`/custom-objects/${customObjectAPIName}/list-views/`, { body, ...options }); } /** * Retrieves an accessible saved view. Views in another object/company or another * requester's private views return not found. * * @example SDK usage * ```ts * const listView = * await client.customObjects.listViews.retrieve( * 'custom_object_api_name', * 'view_api_name', * ); * ``` * * @example HTTP * Representative request and response shapes. * ``` * GET /custom-objects/{custom_object_api_name}/list-views/{view_api_name}/ HTTP/1.1 * Host: rest.ripplingapis.com * Accept: application/json * Rippling-Api-Version: 2024-08-01 * * HTTP/1.1 200 OK * Content-Type: application/json * * { * "id": "string", * "created_at": "2025-01-01T00:00:00Z", * "updated_at": "2025-01-01T00:00:00Z", * "api_name": "string", * "name": "string", * "description": "string", * "visibility": "PRIVATE", * "record_scope": "ALL", * "has_filter": false, * "order_by": "string", * "columns": [ * { * "field": "string" * } * ], * "is_default": false, * "capabilities": { * "can_update": false, * "can_delete": false, * "can_duplicate": false, * "can_share": false, * "can_set_default": false * }, * "query": "string" * } * ``` */ retrieve( customObjectAPIName: string, viewAPIName: string, options?: RequestOptions, ): APIPromise { return this._client.get(path`/custom-objects/${customObjectAPIName}/list-views/${viewAPIName}/`, options); } /** * Updates only the supplied fields of an accessible saved view; omitted fields are * preserved. Null clears description, query, or order_by. Supplied columns replace * visible field selection and order. The API name is immutable and shared views * cannot become private. The company default continues to reference this view * after an edit. Repeating the same update preserves the saved configuration; to * undo an edit, submit the previous values. Records are not modified. Uses * existing Custom Object read consent. Native permissions require ownership for * private views and manage-object access for shared views, sharing, and company * defaults. Object-read consent does not authorize schema or record writes. * * @example SDK usage * ```ts * const listView = * await client.customObjects.listViews.update( * 'custom_object_api_name', * 'view_api_name', * ); * ``` * * @example HTTP * Representative request and response shapes. * ``` * PATCH /custom-objects/{custom_object_api_name}/list-views/{view_api_name}/ HTTP/1.1 * Host: rest.ripplingapis.com * Content-Type: application/json * Accept: application/json * Rippling-Api-Version: 2024-08-01 * * {} * * HTTP/1.1 200 OK * Content-Type: application/json * * { * "id": "string", * "created_at": "2025-01-01T00:00:00Z", * "updated_at": "2025-01-01T00:00:00Z", * "api_name": "string", * "name": "string", * "description": "string", * "visibility": "PRIVATE", * "record_scope": "ALL", * "has_filter": false, * "order_by": "string", * "columns": [ * { * "field": "string" * } * ], * "is_default": false, * "capabilities": { * "can_update": false, * "can_delete": false, * "can_duplicate": false, * "can_share": false, * "can_set_default": false * }, * "query": "string" * } * ``` */ update( customObjectAPIName: string, viewAPIName: string, body: ListViewUpdateParams, options?: RequestOptions, ): APIPromise { return this._client.patch(path`/custom-objects/${customObjectAPIName}/list-views/${viewAPIName}/`, { body, ...options, }); } /** * Removes an accessible saved view from the active collection and clears the * company default if it references this view. Records are not deleted. There is no * public restore operation; retrieve the definition before deletion if you need to * recreate it. A successful deletion returns 204 with no body; a retry after * deletion returns 404. Uses existing Custom Object read consent. Native * permissions require ownership for private views and manage-object access for * shared views, sharing, and company defaults. Object-read consent does not * authorize schema or record writes. * * @example SDK usage * ```ts * await client.customObjects.listViews.delete( * 'custom_object_api_name', * 'view_api_name', * ); * ``` * * @example HTTP * Representative request and response shapes. * ``` * DELETE /custom-objects/{custom_object_api_name}/list-views/{view_api_name}/ HTTP/1.1 * Host: rest.ripplingapis.com * Rippling-Api-Version: 2024-08-01 * * HTTP/1.1 204 No Content * ``` */ delete(customObjectAPIName: string, viewAPIName: string, options?: RequestOptions): APIPromise { return this._client.delete(path`/custom-objects/${customObjectAPIName}/list-views/${viewAPIName}/`, { ...options, headers: buildHeaders([{ Accept: '*/*' }, options?.headers]), }); } } export type ListViewListResponsesPageCursorURL = PageCursorURL; /** * A saved Custom Object grid configuration for selecting, filtering, and ordering * records. */ export interface ListViewListResponse { /** * Read-only internal identifier; address operations using api_name. */ id: string; /** * Stable API name used to address this view. */ api_name: string; /** * Actions available to this caller. */ capabilities: ListViewListResponse.Capabilities; /** * Visible columns, in saved display order. */ columns: Array; /** * Time the view was created, as an ISO 8601 timestamp in UTC. */ created_at: string; /** * Whether this view applies a saved filter in addition to record_scope. The server * resolves it when view_api_name is supplied to record queries. */ has_filter: boolean; /** * Whether this is the company's default view for this object. */ is_default: boolean; /** * Display name of the saved view. */ name: string; /** * MY_RECORDS restricts owners to the authenticated requester when the view is * used. */ record_scope: 'ALL' | 'MY_RECORDS'; /** * Time the view was last updated, as an ISO 8601 timestamp in UTC. */ updated_at: string; /** * PRIVATE belongs to its creator; SHARED is visible within the company. Neither * grants record access. */ visibility: 'PRIVATE' | 'SHARED'; /** * Creator-provided explanation of the records or purpose of this saved view. Null * when no explanation was saved. */ description?: string | null; /** * Saved ordering as one field API name, a space, and lowercase asc or desc, for * example name asc. Null means no saved ordering. */ order_by?: string | null; } export namespace ListViewListResponse { /** * Actions available to this caller. */ export interface Capabilities { /** * Whether the caller may delete this view. */ can_delete: boolean; /** * Whether the caller may create a copy of this definition. */ can_duplicate: boolean; /** * Whether the caller may make this view the company default. */ can_set_default: boolean; /** * Whether the caller may make this private view shared. */ can_share: boolean; /** * Whether the caller may edit this view. */ can_update: boolean; } /** * A visible field within a Custom Object list view. */ export interface Column { /** * Field API name. */ field: string; } } /** * A saved grid definition, including its RQL predicate, for retrieval, editing, or * duplication. */ export interface ListViewCreateResponse { /** * Read-only internal identifier; address operations using api_name. */ id: string; /** * Stable API name used to address this view. */ api_name: string; /** * Actions available to this caller. */ capabilities: ListViewCreateResponse.Capabilities; /** * Visible columns, in saved display order. */ columns: Array; /** * Time the view was created, as an ISO 8601 timestamp in UTC. */ created_at: string; /** * Whether this view applies a saved filter in addition to record_scope. The server * resolves it when view_api_name is supplied to record queries. */ has_filter: boolean; /** * Whether this is the company's default view for this object. */ is_default: boolean; /** * Display name of the saved view. */ name: string; /** * MY_RECORDS restricts owners to the authenticated requester when the view is * used. */ record_scope: 'ALL' | 'MY_RECORDS'; /** * Time the view was last updated, as an ISO 8601 timestamp in UTC. */ updated_at: string; /** * PRIVATE belongs to its creator; SHARED is visible within the company. Neither * grants record access. */ visibility: 'PRIVATE' | 'SHARED'; /** * Creator-provided explanation of the records or purpose of this saved view. Null * when no explanation was saved. */ description?: string | null; /** * Saved ordering as one field API name, a space, and lowercase asc or desc, for * example name asc. Null means no saved ordering. */ order_by?: string | null; /** * Saved RQL predicate, excluding record scope. Null when no predicate is saved. */ query?: string | null; } export namespace ListViewCreateResponse { /** * Actions available to this caller. */ export interface Capabilities { /** * Whether the caller may delete this view. */ can_delete: boolean; /** * Whether the caller may create a copy of this definition. */ can_duplicate: boolean; /** * Whether the caller may make this view the company default. */ can_set_default: boolean; /** * Whether the caller may make this private view shared. */ can_share: boolean; /** * Whether the caller may edit this view. */ can_update: boolean; } /** * A visible field within a Custom Object list view. */ export interface Column { /** * Field API name. */ field: string; } } /** * A saved grid definition, including its RQL predicate, for retrieval, editing, or * duplication. */ export interface ListViewRetrieveResponse { /** * Read-only internal identifier; address operations using api_name. */ id: string; /** * Stable API name used to address this view. */ api_name: string; /** * Actions available to this caller. */ capabilities: ListViewRetrieveResponse.Capabilities; /** * Visible columns, in saved display order. */ columns: Array; /** * Time the view was created, as an ISO 8601 timestamp in UTC. */ created_at: string; /** * Whether this view applies a saved filter in addition to record_scope. The server * resolves it when view_api_name is supplied to record queries. */ has_filter: boolean; /** * Whether this is the company's default view for this object. */ is_default: boolean; /** * Display name of the saved view. */ name: string; /** * MY_RECORDS restricts owners to the authenticated requester when the view is * used. */ record_scope: 'ALL' | 'MY_RECORDS'; /** * Time the view was last updated, as an ISO 8601 timestamp in UTC. */ updated_at: string; /** * PRIVATE belongs to its creator; SHARED is visible within the company. Neither * grants record access. */ visibility: 'PRIVATE' | 'SHARED'; /** * Creator-provided explanation of the records or purpose of this saved view. Null * when no explanation was saved. */ description?: string | null; /** * Saved ordering as one field API name, a space, and lowercase asc or desc, for * example name asc. Null means no saved ordering. */ order_by?: string | null; /** * Saved RQL predicate, excluding record scope. Null when no predicate is saved. */ query?: string | null; } export namespace ListViewRetrieveResponse { /** * Actions available to this caller. */ export interface Capabilities { /** * Whether the caller may delete this view. */ can_delete: boolean; /** * Whether the caller may create a copy of this definition. */ can_duplicate: boolean; /** * Whether the caller may make this view the company default. */ can_set_default: boolean; /** * Whether the caller may make this private view shared. */ can_share: boolean; /** * Whether the caller may edit this view. */ can_update: boolean; } /** * A visible field within a Custom Object list view. */ export interface Column { /** * Field API name. */ field: string; } } /** * A saved grid definition, including its RQL predicate, for retrieval, editing, or * duplication. */ export interface ListViewUpdateResponse { /** * Read-only internal identifier; address operations using api_name. */ id: string; /** * Stable API name used to address this view. */ api_name: string; /** * Actions available to this caller. */ capabilities: ListViewUpdateResponse.Capabilities; /** * Visible columns, in saved display order. */ columns: Array; /** * Time the view was created, as an ISO 8601 timestamp in UTC. */ created_at: string; /** * Whether this view applies a saved filter in addition to record_scope. The server * resolves it when view_api_name is supplied to record queries. */ has_filter: boolean; /** * Whether this is the company's default view for this object. */ is_default: boolean; /** * Display name of the saved view. */ name: string; /** * MY_RECORDS restricts owners to the authenticated requester when the view is * used. */ record_scope: 'ALL' | 'MY_RECORDS'; /** * Time the view was last updated, as an ISO 8601 timestamp in UTC. */ updated_at: string; /** * PRIVATE belongs to its creator; SHARED is visible within the company. Neither * grants record access. */ visibility: 'PRIVATE' | 'SHARED'; /** * Creator-provided explanation of the records or purpose of this saved view. Null * when no explanation was saved. */ description?: string | null; /** * Saved ordering as one field API name, a space, and lowercase asc or desc, for * example name asc. Null means no saved ordering. */ order_by?: string | null; /** * Saved RQL predicate, excluding record scope. Null when no predicate is saved. */ query?: string | null; } export namespace ListViewUpdateResponse { /** * Actions available to this caller. */ export interface Capabilities { /** * Whether the caller may delete this view. */ can_delete: boolean; /** * Whether the caller may create a copy of this definition. */ can_duplicate: boolean; /** * Whether the caller may make this view the company default. */ can_set_default: boolean; /** * Whether the caller may make this private view shared. */ can_share: boolean; /** * Whether the caller may edit this view. */ can_update: boolean; } /** * A visible field within a Custom Object list view. */ export interface Column { /** * Field API name. */ field: string; } } export interface ListViewListParams { cursor?: string; /** * The maximum number of results to return. Defaults to 50. Maximum is 100. */ limit?: number; } export interface ListViewCreateParams { /** * Ordered, nonempty, unique field selection. */ columns: Array; /** * Nonblank display name. */ name: string; /** * Case-sensitive API name, unique among active company views and immutable after * creation. Use letters, digits, and underscores with a \_\_c suffix. Generated * when omitted. */ api_name?: string; /** * Creator-provided explanation of the records or purpose of this saved view. * Defaults to null when omitted. */ description?: string | null; /** * One sortable field API name, a space, and lowercase asc or desc, for example * name asc. Null clears saved ordering. */ order_by?: string | null; /** * Saved RQL predicate; null clears it. */ query?: string | null; /** * ALL includes all records the caller may read; MY_RECORDS restricts owners to the * authenticated requester when the view is used. Defaults to ALL when omitted. */ record_scope?: 'ALL' | 'MY_RECORDS'; /** * PRIVATE belongs to its creator; SHARED is visible within the company. Neither * grants record access. Defaults to PRIVATE when omitted. */ visibility?: 'PRIVATE' | 'SHARED'; } export namespace ListViewCreateParams { /** * A field selected for display at its position in a saved grid's ordered columns. */ export interface Column { /** * Field API name. */ field: string; } } export interface ListViewUpdateParams { /** * Ordered, nonempty, unique field selection. */ columns?: Array; /** * Creator-provided explanation of the records or purpose of this saved view. Null * clears the explanation; omission preserves it. */ description?: string | null; /** * Nonblank display name. */ name?: string; /** * One sortable field API name, a space, and lowercase asc or desc, for example * name asc. Null clears saved ordering. */ order_by?: string | null; /** * Saved RQL predicate; null clears it. */ query?: string | null; /** * ALL includes all records the caller may read; MY_RECORDS restricts owners to the * authenticated requester when the view is used. Omission preserves the saved * scope. */ record_scope?: 'ALL' | 'MY_RECORDS'; /** * PRIVATE belongs to its creator; SHARED is visible within the company. Neither * grants record access. Shared views cannot become private. Omission preserves * visibility. */ visibility?: 'PRIVATE' | 'SHARED'; } export namespace ListViewUpdateParams { /** * A field selected for display at its position in a saved grid's ordered columns. */ export interface Column { /** * Field API name. */ field: string; } } ListViews.Capabilities = CapabilitiesAPICapabilities; ListViews.Default = Default; export declare namespace ListViews { export { type ListViewListResponse as ListViewListResponse, type ListViewCreateResponse as ListViewCreateResponse, type ListViewRetrieveResponse as ListViewRetrieveResponse, type ListViewUpdateResponse as ListViewUpdateResponse, type ListViewListResponsesPageCursorURL as ListViewListResponsesPageCursorURL, type ListViewListParams as ListViewListParams, type ListViewCreateParams as ListViewCreateParams, type ListViewUpdateParams as ListViewUpdateParams, }; export { CapabilitiesAPICapabilities as Capabilities, type CapabilityRetrieveResponse as CapabilityRetrieveResponse, }; export { Default as Default, type DefaultUpdateResponse as DefaultUpdateResponse, type DefaultUpdateParams as DefaultUpdateParams, }; }