npm package: @seal.run/sdk
Description: Seal Platform SDK for building custom entity applications
Author: Seal
Latest version: 0.1.15
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# @seal.run/sdk

This is the official JavaScript/TypeScript SDK intended for users of the [Seal](https://seal.run/) platform to develop custom entities.

## Getting started

Install the seal-sdk package via npm or yarn:

```bash
npm install @seal.run/sdk
# or
yarn add @seal.run/sdk
```

## Seal methods

The `Seal` class contains many useful methods for interacting with the platform:

```typescript
import { Seal } from "@seal.run/sdk";
```

| Method                                                                                                                                             | Description                                                                                                                                                                                                                             | Parameters                                                                                                                                                                                                                                                                                                                                                                                                                       | Returns                                                 |
| :------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ |
| `updateFieldValue(fieldName: string, value: FieldValue)`                                                                                           | Updates the value for a field in the entity.                                                                                                                                                                                            | - `fieldName`: The name of the field to update.<br>- `value`: The new value for the field.                                                                                                                                                                                                                                                                                                                                       | `void`                                                  |
| `updateFieldValueInEntity(entityId: string, fieldName: string, value: FieldValue)`                                                                 | Updates the value for a field in the entity with the given `entityId`.                                                                                                                                                                  | - `entityId`: The id of the entity to update.<br>- `fieldName`: The name of the field to update.<br>- `value`: The new value for the field.                                                                                                                                                                                                                                                                                      | `void`                                                  |
| `addField(fieldName: string, type: FieldType)`                                                                                                     | Adds a new field to the entity.                                                                                                                                                                                                         | - `fieldName`: The name of the field to add.<br>- `type`: The `FieldType` of the new field.                                                                                                                                                                                                                                                                                                                                      | `void`                                                  |
| `getUserContext()`                                                                                                                                 | Returns information about the user who is currently interacting with the custom entity.                                                                                                                                                 | None                                                                                                                                                                                                                                                                                                                                                                                                                             | `UserContext`                                           |
| `getPreviewContext()`                                                                                                                              | Returns information about entity in which the SDK is being run, when running in a reference preview                                                                                                                                     | None                                                                                                                                                                                                                                                                                                                                                                                                                             | `{id: string \| null, version: string \| null} \| null` |
| `deleteField(fieldName: string)`                                                                                                                   | Deletes a field from the entity.                                                                                                                                                                                                        | - `fieldName`: The name of the field to delete.                                                                                                                                                                                                                                                                                                                                                                                  | `void`                                                  |
| `getEntity(): EntityData \| null`                                                                                                                  | Returns the currently loaded entity data.                                                                                                                                                                                               | None.                                                                                                                                                                                                                                                                                                                                                                                                                            | `EntityData \| null`                                    |
| `onEntityData(callback: (entity: EntityData \| null) => void)`                                                                                     | Subscribes a callback function to receive updates whenever the entity data changes.                                                                                                                                                     | - `callback`: A function that receives the updated `EntityData` or `null`.                                                                                                                                                                                                                                                                                                                                                       | `void`                                                  |
| `getFields(entity: EntityData)`                                                                                                                    | Retrieves and sorts an entity's fields by name.                                                                                                                                                                                         | - `entity`: The `EntityData` object.                                                                                                                                                                                                                                                                                                                                                                                             | `Array<{ name: string; data: any }>`                    |
| `getField(fieldName: string)`                                                                                                                      | Retrieves a specific field from the current entity data.                                                                                                                                                                                | - `fieldName`: The name of the field to retrieve.                                                                                                                                                                                                                                                                                                                                                                                | `any`                                                   |
| `convertSimpleToAdvancedSearchConfig(config: SimpleOrAdvancedSearchConfig \| null \| undefined): AdvancedSearchConfig`                             | Converts a simple search configuration to an advanced search configuration.                                                                                                                                                             | - `config`: The `SimpleOrAdvancedSearchConfig` to convert.                                                                                                                                                                                                                                                                                                                                                                       | `AdvancedSearchConfig`                                  |
| `getEntityById(entityId: string)`                                                                                                                  | Fetches an entity by its ID.                                                                                                                                                                                                            | - `entityId`: The ID of the entity to retrieve.                                                                                                                                                                                                                                                                                                                                                                                  | `Promise<EntityData \| null>`                           |
| `searchEntities({ queryConfig, first?, after?, directWorkspaceOnly? })`                                                                            | Searches for entities using an advanced search configuration with optional pagination.                                                                                                                                                  | - `queryConfig`: The `AdvancedSearchConfig` object defining filters, sorting, etc.<br>- `first`: Optional number of results (max: 1000 per page).<br>- `after`: Optional cursor for pagination.<br>- `directWorkspaceOnly`: If true, searches only the current workspace (default: false).                                                                                                                                       | `Promise<SearchEntitiesResponse>`                       |
| `searchReferenceField({ entityId, fieldName, search }: { entityId: string; fieldName: string; search: string })`                                   | Searches for entities referenced by a specific field based on a search string.                                                                                                                                                          | - `entityId`: The ID of the entity to search within.<br>- `fieldName`: The name of the reference field.<br>- `search`: The query string for the search.                                                                                                                                                                                                                                                                          | `Promise<SearchResult[]>`                               |
| `createIntoReferenceField({ fieldName, initialFieldValues }: { fieldName: string; initialFieldValues: Record<string, unknown> })`                  | Creates a new entity in the provided reference field. The reference field must be filtered to only allow entities of a particular template.                                                                                             | - `fieldName`: The name of the reference field to create into.<br>- `initialFieldValues`: Initial field values for the new entity.                                                                                                                                                                                                                                                                                               | `Promise<EntityData \| null>`                           |
| `goToEntity(entityId: string, options?: { version?: string \| null; openInSameTab?: boolean; queryParams?: Record<string, string \| undefined> })` | Navigates the parent application to a specific entity page.                                                                                                                                                                             | - `entityId`: The ID of the entity to navigate to.<br>- `options.version`: Optional specific version to navigate to (e.g., `"2.0"`). If not provided, navigates to the live/active version.<br>- `options.openInSameTab`: If `true`, opens in the same tab. Default is `false` (opens in a new tab).<br>- `options.queryParams`: Optional object of query parameters to append to the URL (e.g., `{ viewAllVersions: "true" }`). | `void`                                                  |
| `requestESignature()`                                                                                                                              | Requests e-signature authentication from the user. Opens a modal for the user to re-authenticate via SSO or password. Only triggers authentication if CFR21 Compliance is enabled for the organization; otherwise succeeds immediately. | None                                                                                                                                                                                                                                                                                                                                                                                                                             | `Promise<boolean>`                                      |

## Development

Custom entities can be developed locally by clicking on `Development mode` on the page for any type that uses custom content. You will be prompted to start a local dev server and refresh the page.

## Uploading to Seal

Once development is complete, build the app. Your app **must** contain an `index.html` file at the root level and use relative paths for assets to ensure that the build is portable and can be rendered inside Seal.

In Vite, relative asset paths can be enforced by adding the following to your config:

```typescript
  base: './',
```

## License

See the [LICENSE](LICENSE) file for details.