@epilot/sdk 2.2.6 → 2.3.0

package/docs/{data-management.md → data-governance.md}

@@ -1,6 +1,7 @@
-# Data Management API
+# Data Governance API
 
-- **Full API Docs:** [https://docs.epilot.io/api/data-management](https://docs.epilot.io/api/data-management)
+- **Base URL:** `https://data-governance.sls.epilot.io`
+- **Full API Docs:** [https://docs.epilot.io/api/data-governance](https://docs.epilot.io/api/data-governance)
 
 ## Usage
 
@@ -8,32 +9,36 @@
 import { epilot } from '@epilot/sdk'
 
 epilot.authorize(() => '<token>')
-const { data } = await epilot.dataManagement.queryEntities(...)
+const { data } = await epilot.dataGovernance.queryEntities(...)
 ```
 
 ### Tree-shakeable import
 
 ```ts
-import { getClient, authorize } from '@epilot/sdk/data-management'
+import { getClient, authorize } from '@epilot/sdk/data-governance'
 
-const dataManagementClient = getClient()
-authorize(dataManagementClient, () => '<token>')
-const { data } = await dataManagementClient.queryEntities(...)
+const dataGovernanceClient = getClient()
+authorize(dataGovernanceClient, () => '<token>')
+const { data } = await dataGovernanceClient.queryEntities(...)
 ```
 
 ## Operations
 
-**Data Management**
+**Query**
 - [`queryEntities`](#queryentities)
+
+**Auditable Jobs**
 - [`createJob`](#createjob)
 - [`updateJob`](#updatejob)
 - [`getJob`](#getjob)
 - [`getJobReportUrl`](#getjobreporturl)
-- [`getConfig`](#getconfig)
 - [`createJobForConfig`](#createjobforconfig)
+- [`listJobs`](#listjobs)
+
+**Data Lifecycle Configs**
+- [`getConfig`](#getconfig)
 - [`upsertConfig`](#upsertconfig)
 - [`listConfigs`](#listconfigs)
-- [`listJobs`](#listjobs)
 
 **Schemas**
 - [`ConfigType`](#configtype)
@@ -61,9 +66,9 @@ const { data } = await dataManagementClient.queryEntities(...)
 
 ### `queryEntities`
 
-Query entities using a saved view with additional data filters
+Query entities matching a data lifecycle config
 
-`POST /data-management/v1/{entity_schema}/query`
+`POST /data-governance/v1/{entity_schema}/query`
 
 ```ts
 const { data } = await client.queryEntities(
@@ -110,7 +115,7 @@ const { data } = await client.queryEntities(
 
 Create a new job run
 
-`POST /data-management/v1/{entity_schema}/jobs`
+`POST /data-governance/v1/{entity_schema}/jobs`
 
 ```ts
 const { data } = await client.createJob(
@@ -162,7 +167,7 @@ const { data } = await client.createJob(
 
 Update an existing job run
 
-`PATCH /data-management/v1/{entity_schema}/jobs/{job_id}`
+`PATCH /data-governance/v1/{entity_schema}/jobs/{job_id}`
 
 ```ts
 const { data } = await client.updateJob(
@@ -217,9 +222,9 @@ const { data } = await client.updateJob(
 
 ### `getJob`
 
-Get a job by id
+Get a job by ID
 
-`GET /data-management/v1/jobs/{job_id}`
+`GET /data-governance/v1/jobs/{job_id}`
 
 ```ts
 const { data } = await client.getJob({
@@ -262,7 +267,7 @@ const { data } = await client.getJob({
 
 Get report download URL for a job
 
-`GET /data-management/v1/jobs/{job_id}/report-url`
+`GET /data-governance/v1/jobs/{job_id}/report-url`
 
 ```ts
 const { data } = await client.getJobReportUrl({
@@ -286,9 +291,9 @@ const { data } = await client.getJobReportUrl({
 
 ### `getConfig`
 
-Get a config by id
+Get a config by ID
 
-`GET /data-management/v1/configs/{config_id}`
+`GET /data-governance/v1/configs/{config_id}`
 
 ```ts
 const { data } = await client.getConfig({
@@ -340,7 +345,7 @@ const { data } = await client.getConfig({
 
 Trigger a manual job run for a config
 
-`POST /data-management/v1/configs/{config_id}/jobs`
+`POST /data-governance/v1/configs/{config_id}/jobs`
 
 ```ts
 const { data } = await client.createJobForConfig({
@@ -381,9 +386,9 @@ const { data } = await client.createJobForConfig({
 
 ### `upsertConfig`
 
-Upsert config
+Create or update a data lifecycle config
 
-`POST /data-management/v1/{entity_schema}/configs`
+`POST /data-governance/v1/{entity_schema}/configs`
 
 ```ts
 const { data } = await client.upsertConfig(
@@ -459,9 +464,9 @@ const { data } = await client.upsertConfig(
 
 ### `listConfigs`
 
-List configs
+List data lifecycle configs
 
-`GET /data-management/v1/configs`
+`GET /data-governance/v1/configs`
 
 ```ts
 const { data } = await client.listConfigs({
@@ -521,9 +526,9 @@ const { data } = await client.listConfigs({
 
 ### `listJobs`
 
-List jobs
+List job runs
 
-`GET /data-management/v1/jobs`
+`GET /data-governance/v1/jobs`
 
 ```ts
 const { data } = await client.listJobs({
@@ -576,7 +581,9 @@ const { data } = await client.listJobs({
 
 ### `ConfigType`
 
-Type of configuration (e.g. deletion)
+The governance action type. Determines what operation is performed on
+matched entities when a job runs. Currently only `deletion` is supported.
+
 
 ```ts
 type ConfigType = "deletion"
@@ -584,24 +591,41 @@ type ConfigType = "deletion"
 
 ### `JobStatus`
 
+Current execution status of a job run.
+- `in_progress` — the job is actively processing entities.
+- `success` — the job completed without critical errors.
+- `failed` — the job terminated due to an error.
+
+
 ```ts
 type JobStatus = "in_progress" | "success" | "failed"
 ```
 
 ### `JobTrigger`
 
+Indicates how the job was initiated.
+- `schedule` — automatically created by the background scheduler.
+- `manual` — explicitly triggered by a user via the API.
+
+
 ```ts
 type JobTrigger = "schedule" | "manual"
 ```
 
 ### `JobReportFormat`
 
+File format of the job report. Currently only CSV is supported.
+
 ```ts
 type JobReportFormat = "csv"
 ```
 
 ### `JobReport`
 
+Reference to a report file stored in S3 that details the outcome of a
+job run (e.g., which entities were deleted or failed).
+
+
 ```ts
 type JobReport = {
   bucket?: string
@@ -612,6 +636,8 @@ type JobReport = {
 
 ### `CreateJobRequest`
 
+Request payload for creating a new job run.
+
 ```ts
 type CreateJobRequest = {
   type: "deletion"
@@ -624,7 +650,12 @@ type CreateJobRequest = {
 
 ### `JobDetails`
 
-Generic, type-specific job details payload (e.g. matched count, deleted count, failed count, etc.).
+Type-specific job outcome payload. The shape depends on the config type.
+For `deletion` jobs, typical fields include:
+- `matched_count` — total entities matched by the query
+- `deleted_count` — entities successfully deleted
+- `failed_count` — entities that could not be deleted
+
 
 ```ts
 type JobDetails = Record<string, unknown>
@@ -632,6 +663,10 @@ type JobDetails = Record<string, unknown>
 
 ### `UpdateJobRequest`
 
+Partial update payload for an existing job. Only the fields provided
+will be merged into the job record.
+
+
 ```ts
 type UpdateJobRequest = {
   status?: "in_progress" | "success" | "failed"
@@ -648,6 +683,11 @@ type UpdateJobRequest = {
 
 ### `Job`
 
+Represents a single execution run of a data lifecycle config. Tracks the
+full lifecycle from creation through completion, including outcome
+details and an optional downloadable report.
+
+
 ```ts
 type Job = {
   id: string
@@ -674,6 +714,8 @@ type Job = {
 
 ### `ListJobsResponse`
 
+Paginated response containing a list of job runs.
+
 ```ts
 type ListJobsResponse = {
   jobs?: Array<{
@@ -703,6 +745,8 @@ type ListJobsResponse = {
 
 ### `JobReportUrlResponse`
 
+Contains a time-limited pre-signed URL to download a job report.
+
 ```ts
 type JobReportUrlResponse = {
   url?: string
@@ -712,12 +756,22 @@ type JobReportUrlResponse = {
 
 ### `QueryFilterType`
 
+Predefined data governance filter types that can be layered on top of
+a saved view to narrow down target entities:
+- `entity_workflows_only_in_closed_or_cancelled_status` — include only
+  entities whose own workflows are all in a closed/cancelled state.
+- `no_related_entities` — include only entitie
+
 ```ts
 type QueryFilterType = "entity_workflows_only_in_closed_or_cancelled_status" | "no_related_entities" | "related_entities_all_in_closed_or_cancelled_status" | "related_entities_workflows_only_in_closed_or_cancelled_status" | "no_email_communication_since"
 ```
 
 ### `QueryFilter`
 
+A single governance filter condition applied during entity querying.
+The required and optional fields depend on the `type`.
+
+
 ```ts
 type QueryFilter = {
   type: "entity_workflows_only_in_closed_or_cancelled_status" | "no_related_entities" | "related_entities_all_in_closed_or_cancelled_status" | "related_entities_workflows_only_in_closed_or_cancelled_status" | "no_email_communication_since"
@@ -730,6 +784,10 @@ type QueryFilter = {
 
 ### `QueryConfig`
 
+Defines the query used by a data lifecycle config to identify target
+entities. Combines a saved view with optional governance filters.
+
+
 ```ts
 type QueryConfig = {
   saved_view_id: string
@@ -746,6 +804,10 @@ type QueryConfig = {
 
 ### `QueryEntitiesRequest`
 
+Request body for the query endpoint. Extends `QueryConfig` with
+pagination and projection options.
+
+
 ```ts
 type QueryEntitiesRequest = {
   saved_view_id: string
@@ -766,6 +828,8 @@ type QueryEntitiesRequest = {
 
 ### `QueryEntitiesResult`
 
+Response from the entity query endpoint.
+
 ```ts
 type QueryEntitiesResult = {
   hits?: number
@@ -775,6 +839,10 @@ type QueryEntitiesResult = {
 
 ### `ConfigSchedule`
 
+Interval-based schedule. The governance engine will create a job every
+`interval_days` days, optionally bounded by start and end dates.
+
+
 ```ts
 type ConfigSchedule = {
   frequency: "interval"
@@ -786,6 +854,10 @@ type ConfigSchedule = {
 
 ### `IntervalConfigSchedule`
 
+Interval-based schedule. The governance engine will create a job every
+`interval_days` days, optionally bounded by start and end dates.
+
+
 ```ts
 type IntervalConfigSchedule = {
   frequency: "interval"
@@ -797,6 +869,8 @@ type IntervalConfigSchedule = {
 
 ### `UpsertConfigRequest`
 
+Request payload for creating or updating a data lifecycle config.
+
 ```ts
 type UpsertConfigRequest = {
   type: "deletion"
@@ -824,6 +898,10 @@ type UpsertConfigRequest = {
 
 ### `Config`
 
+A data lifecycle config defining an automated policy (e.g., scheduled
+entity deletion) for a specific entity schema.
+
+
 ```ts
 type Config = {
   id: string
@@ -857,12 +935,19 @@ type Config = {
 
 ### `DeletionRelationEntitySchema`
 
+Entity schema slug that can be specified as a cascading deletion
+target. When a primary entity is deleted, related entities of these
+schemas are also removed.
+
+
 ```ts
 type DeletionRelationEntitySchema = "contact" | "file" | "opportunity" | "order" | "meter" | "ticket" | "message" | "account" | "submission" | "contract"
 ```
 
 ### `ListConfigsResponse`
 
+Paginated response containing a list of data lifecycle configs.
+
 ```ts
 type ListConfigsResponse = {
   configs?: Array<{

package/docs/deduplication.md

@@ -25,11 +25,16 @@ const { data } = await deduplicationClient.deduplicate(...)
 ## Operations
 
 - [`deduplicate`](#deduplicate)
+- [`deduplicateAsync`](#deduplicateasync)
+- [`getDeduplicationJob`](#getdeduplicationjob)
 
 **Schemas**
 - [`DeduplicateRequestBody`](#deduplicaterequestbody)
 - [`DeduplicateRequestResponse`](#deduplicaterequestresponse)
 - [`Entity`](#entity)
+- [`DeduplicateAsyncResponse`](#deduplicateasyncresponse)
+- [`JobStatus`](#jobstatus)
+- [`DeduplicationJob`](#deduplicationjob)
 
 ### `deduplicate`
 
@@ -79,6 +84,75 @@ const { data } = await client.deduplicate(
 
 ---
 
+### `deduplicateAsync`
+
+Submits an async deduplication job. Returns a job ID immediately. Poll GET /v1/deduplicate/jobs/{jobId} for status.
+
+`POST /v1/deduplicate/job`
+
+```ts
+const { data } = await client.deduplicateAsync(
+  null,
+  [
+    {
+      toKeep: 'string',
+      toDelete: ['string']
+    }
+  ],
+)
+```
+
+---
+
+### `getDeduplicationJob`
+
+Returns the current status of an async deduplication job
+
+`GET /v1/deduplicate/jobs/{jobId}`
+
+```ts
+const { data } = await client.getDeduplicationJob({
+  jobId: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "jobId": "string",
+  "status": "pending",
+  "message": "string",
+  "result": [
+    {
+      "_id": "string",
+      "_org": "string",
+      "_schema": "string",
+      "_created_at": "1970-01-01T00:00:00.000Z",
+      "_updated_at": "1970-01-01T00:00:00.000Z",
+      "_created_by": "string",
+      "created_by": "string",
+      "_tags": ["string"],
+      "_acl": {},
+      "_owners": [
+        {
+          "org_id": "string",
+          "user_id": "string"
+        }
+      ],
+      "type": "string"
+    }
+  ],
+  "createdAt": "1970-01-01T00:00:00.000Z",
+  "updatedAt": "1970-01-01T00:00:00.000Z"
+}
+```
+
+</details>
+
+---
+
 ## Schemas
 
 ### `DeduplicateRequestBody`
@@ -133,3 +207,51 @@ type Entity = {
   type?: string
 }
 ```
+
+### `DeduplicateAsyncResponse`
+
+Response returned immediately when a deduplication job is submitted
+
+```ts
+type DeduplicateAsyncResponse = {
+  jobId: string
+  status: "pending" | "processing" | "completed" | "failed"
+  message: string
+}
+```
+
+### `JobStatus`
+
+```ts
+type JobStatus = "pending" | "processing" | "completed" | "failed"
+```
+
+### `DeduplicationJob`
+
+Represents an async deduplication job
+
+```ts
+type DeduplicationJob = {
+  jobId: string
+  status: "pending" | "processing" | "completed" | "failed"
+  message?: string
+  result?: Array<{
+    _id: string
+    _org?: string
+    _schema?: string
+    _created_at?: string // date-time
+    _updated_at?: string // date-time
+    _created_by?: string | number
+    created_by?: string | number
+    _tags?: string[]
+    _acl?: Record<string, string[]>
+    _owners?: Array<{
+      org_id: { ... }
+      user_id: { ... }
+    }>
+    type?: string
+  }>
+  createdAt: string // date-time
+  updatedAt: string // date-time
+}
+```