@epilot/sdk 2.1.0-rc.0 → 2.1.0

package/docs/document.md

@@ -0,0 +1,590 @@
+# Document API
+
+- **Base URL:** `https://document.sls.epilot.io`
+- **Full API Docs:** [https://docs.epilot.io/api/document](https://docs.epilot.io/api/document)
+
+## Usage
+
+```ts
+import { epilot } from '@epilot/sdk'
+
+epilot.authorize(() => '<token>')
+const { data } = await epilot.document.getTemplateMeta(...)
+```
+
+### Tree-shakeable import
+
+```ts
+import { getClient, authorize } from '@epilot/sdk/document'
+
+const documentClient = getClient()
+authorize(documentClient, () => '<token>')
+const { data } = await documentClient.getTemplateMeta(...)
+```
+
+## Operations
+
+**Documents**
+- [`getTemplateMeta`](#gettemplatemeta)
+- [`generateDocumentV2`](#generatedocumentv2)
+- [`convertDocument`](#convertdocument)
+
+**Schemas**
+- [`S3Reference`](#s3reference)
+- [`ErrorOutput`](#erroroutput)
+- [`InvalidCustomVariableErrorDetails`](#invalidcustomvariableerrordetails)
+- [`InvalidCustomVariableErrorDetail`](#invalidcustomvariableerrordetail)
+- [`InternalErrorDetails`](#internalerrordetails)
+- [`InternalErrorDetail`](#internalerrordetail)
+- [`DocxTemplaterErrorDetails`](#docxtemplatererrordetails)
+- [`DocxTemplaterErrorDetail`](#docxtemplatererrordetail)
+- [`ErrorCode`](#errorcode)
+- [`TemplateSettings`](#templatesettings)
+- [`DocumentMetaRequest`](#documentmetarequest)
+- [`DocumentMetaResponse`](#documentmetaresponse)
+- [`DocumentGenerationV2Request`](#documentgenerationv2request)
+- [`DocumentGenerationV2Response`](#documentgenerationv2response)
+- [`ConvertDocumentRequest`](#convertdocumentrequest)
+- [`ConvertDocumentResponse`](#convertdocumentresponse)
+
+### `getTemplateMeta`
+
+Get metadata for a document template
+
+`POST /v2/documents:meta`
+
+```ts
+const { data } = await client.getTemplateMeta(
+  null,
+  {
+    template_document: {
+      s3ref: {
+        bucket: 'document-api-prod',
+        key: 'uploads/my-template.pdf'
+      }
+    }
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "page_margins": {
+    "top": 2.54,
+    "bottom": 2.54,
+    "left": 2.54,
+    "right": 2.54,
+    "header": 2.54,
+    "footer": 2.54
+  },
+  "variables": ["order.billing_contact.0.salutation", "order.billing_contact.0.title", "order_table", "stayHardStatic", "opportunity[attribute_name]", "opportunity[\"attribute_name\"]", "opportunity.[attribute_name]", "attribute_name", "opportunities.0.attribute_name", "opportunities[0].attribute_name", "contact.opportunities[0].attribute_name", "opportunities[Primary].attribute_name"]
+}
+```
+
+</details>
+
+---
+
+### `generateDocumentV2`
+
+Generates documents from templates with variables.
+
+`POST /v2/documents:generate`
+
+```ts
+const { data } = await client.generateDocumentV2(
+  {
+    job_id: 'example',
+    mode: 'example',
+    preview_mode: 'example',
+  },
+  {
+    template_document: {
+      filename: 'my-template-{{order.order_number}}.docx',
+      s3ref: {
+        bucket: 'document-api-prod',
+        key: 'uploads/my-template.pdf'
+      }
+    },
+    context_entity_id: 'bcd0aab9-b544-42b0-8bfb-6d449d02eacc',
+    user_id: 100321,
+    language: 'de',
+    variable_payload: {
+      additionalProperties: 'string'
+    },
+    context_data: {
+      additionalProperties: 'string'
+    },
+    template_settings: {
+      custom_margins: {
+        top: 2.54,
+        bottom: 2.54
+      },
+      suggested_margins: {
+        top: 2.54,
+        bottom: 2.54
+      },
+      display_margin_guidelines: true,
+      enable_data_table_margin_autofix: false,
+      template_with_datatable: false,
+      enabled_template_settings_persistence: false,
+      misconfigured_margins: false,
+      file_entity_id: '1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p'
+    }
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  "job_status": "STARTED",
+  "message": "string",
+  "ics_output": {
+    "output_document": {
+      "s3ref": {
+        "bucket": "document-api-preview-prod",
+        "key": "preview/my-appointment.ics"
+      }
+    }
+  },
+  "pdf_output": {
+    "preview_url": "https://document-api-prod.s3.eu-central-1.amazonaws.com/preview/my-template-OR-001.pdf",
+    "output_document": {
+      "s3ref": {
+        "bucket": "document-api-preview-prod",
+        "key": "preview/my-template.pdf"
+      }
+    }
+  },
+  "docx_output": {
+    "preview_url": "https://document-api-prod.s3.eu-central-1.amazonaws.com/preview/my-template-OR-001.docx",
+    "output_document": {
+      "s3ref": {
+        "bucket": "document-api-preview-prod",
+        "key": "preview/my-template.docx"
+      }
+    }
+  },
+  "xlsx_output": {
+    "preview_url": "https://document-api-prod.s3.eu-central-1.amazonaws.com/preview/my-template-OR-001.xlsx",
+    "output_document": {
+      "s3ref": {
+        "bucket": "document-api-preview-prod",
+        "key": "preview/my-template.xlsx"
+      }
+    }
+  },
+  "error_output": {
+    "error_message": "string",
+    "error_code": "PARSE_ERROR",
+    "error_details": [
+      {
+        "explanation": "string",
+        "context": {
+          "invalid_variables": [
+            {
+              "variable": "string",
+              "error": "string"
+            }
+          ]
+        }
+      }
+    ]
+  },
+  "variable_payload": {
+    "additionalProperties": "string"
+  },
+  "template_settings": {
+    "custom_margins": {
+      "top": 2.54,
+      "bottom": 2.54
+    },
+    "suggested_margins": {
+      "top": 2.54,
+      "bottom": 2.54
+    },
+    "display_margin_guidelines": true,
+    "enable_data_table_margin_autofix": false,
+    "template_with_datatable": false,
+    "enabled_template_settings_persistence": false,
+    "misconfigured_margins": false,
+    "file_entity_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
+  }
+}
+```
+
+</details>
+
+---
+
+### `convertDocument`
+
+Converts a document to a different format.
+
+`POST /v2/documents:convert`
+
+```ts
+const { data } = await client.convertDocument(
+  null,
+  {
+    language: 'de',
+    input_document: {
+      s3ref: {
+        bucket: 'document-api-prod',
+        key: 'uploads/my-template.pdf'
+      }
+    },
+    output_format: 'pdf',
+    output_filename: 'converted.pdf'
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "output_document": {
+    "preview_url": "https://document-api-prod.s3.eu-central-1.amazonaws.com/preview/converted.pdf",
+    "s3ref": {
+      "bucket": "document-api-prod",
+      "key": "uploads/my-template.pdf"
+    }
+  }
+}
+```
+
+</details>
+
+---
+
+## Schemas
+
+### `S3Reference`
+
+```ts
+type S3Reference = {
+  bucket: string
+  key: string
+}
+```
+
+### `ErrorOutput`
+
+```ts
+type ErrorOutput = {
+  error_message?: string
+  error_code?: "PARSE_ERROR" | "DOC_TO_PDF_CONVERT_ERROR" | "INTERNAL_ERROR" | "INVALID_TEMPLATE_FORMAT"
+  error_details?: Array<{
+    explanation?: string
+    context?: {
+      invalid_variables?: { ... }
+    }
+  }> | Array<{
+    items?: {
+      name?: { ... }
+      message?: { ... }
+      stack?: { ... }
+      cause?: { ... }
+    }
+  }> | Array<{
+    id?: string
+    context?: string
+    explanation?: string
+  }>
+}
+```
+
+### `InvalidCustomVariableErrorDetails`
+
+Error details for invalid custom variables. This error will appear under 'PARSE_ERROR' error code.
+
+```ts
+type InvalidCustomVariableErrorDetails = Array<{
+  explanation?: string
+  context?: {
+    invalid_variables?: Array<{
+      variable?: { ... }
+      error?: { ... }
+    }>
+  }
+}>
+```
+
+### `InvalidCustomVariableErrorDetail`
+
+```ts
+type InvalidCustomVariableErrorDetail = {
+  explanation?: string
+  context?: {
+    invalid_variables?: Array<{
+      variable?: { ... }
+      error?: { ... }
+    }>
+  }
+}
+```
+
+### `InternalErrorDetails`
+
+Error details for internal error. This error will appear under 'INTERNAL_ERROR' error code.
+
+```ts
+type InternalErrorDetails = Array<{
+  items?: {
+    name?: string
+    message?: string
+    stack?: string
+    cause?: string
+  }
+}>
+```
+
+### `InternalErrorDetail`
+
+Internal error detail
+
+```ts
+type InternalErrorDetail = {
+  name?: string
+  message?: string
+  stack?: string
+  cause?: string
+}
+```
+
+### `DocxTemplaterErrorDetails`
+
+Error details for DocxTemplater error. This error will appear under 'PARSE_ERROR' error code.
+See https://docxtemplater.com/docs/errors/#error-schema for more details.
+
+
+```ts
+type DocxTemplaterErrorDetails = Array<{
+  id?: string
+  context?: string
+  explanation?: string
+}>
+```
+
+### `DocxTemplaterErrorDetail`
+
+DocxTemplater error detail
+
+```ts
+type DocxTemplaterErrorDetail = {
+  id?: string
+  context?: string
+  explanation?: string
+}
+```
+
+### `ErrorCode`
+
+Error codes for document generation:
+- PARSE_ERROR - Error while parsing the document. Normally related with a bad template using the wrong DocxTemplater syntax.
+- DOC_TO_PDF_CONVERT_ERROR - Error while converting the document to PDF. Normally related with a ConvertAPI failure.
+- INTERNAL_ERROR - In
+
+```ts
+type ErrorCode = "PARSE_ERROR" | "DOC_TO_PDF_CONVERT_ERROR" | "INTERNAL_ERROR" | "INVALID_TEMPLATE_FORMAT"
+```
+
+### `TemplateSettings`
+
+Template Settings for document generation
+
+```ts
+type TemplateSettings = {
+  custom_margins?: {
+    top?: number
+    bottom?: number
+  }
+  suggested_margins?: {
+    top?: number
+    bottom?: number
+  }
+  display_margin_guidelines?: boolean
+  enable_data_table_margin_autofix?: boolean
+  template_with_datatable?: boolean
+  enabled_template_settings_persistence?: boolean
+  misconfigured_margins?: boolean
+  file_entity_id?: string // uuid
+}
+```
+
+### `DocumentMetaRequest`
+
+```ts
+type DocumentMetaRequest = {
+  template_document?: {
+    s3ref?: {
+      bucket: { ... }
+      key: { ... }
+    }
+  }
+}
+```
+
+### `DocumentMetaResponse`
+
+```ts
+type DocumentMetaResponse = {
+  page_margins?: {
+    top?: number
+    bottom?: number
+    left?: number
+    right?: number
+    header?: number
+    footer?: number
+  }
+  variables?: string[]
+}
+```
+
+### `DocumentGenerationV2Request`
+
+```ts
+type DocumentGenerationV2Request = {
+  template_document: {
+    filename?: string
+    s3ref?: {
+      bucket: { ... }
+      key: { ... }
+    }
+  }
+  context_entity_id?: string // uuid
+  user_id?: string
+  language?: string
+  variable_payload?: {
+    additionalProperties?: string
+  }
+  context_data?: {
+    additionalProperties?: string
+  }
+  template_settings?: {
+    custom_margins?: {
+      top?: { ... }
+      bottom?: { ... }
+    }
+    suggested_margins?: {
+      top?: { ... }
+      bottom?: { ... }
+    }
+    display_margin_guidelines?: boolean
+    enable_data_table_margin_autofix?: boolean
+    template_with_datatable?: boolean
+    enabled_template_settings_persistence?: boolean
+    misconfigured_margins?: boolean
+    file_entity_id?: string // uuid
+  }
+}
+```
+
+### `DocumentGenerationV2Response`
+
+```ts
+type DocumentGenerationV2Response = {
+  job_id?: string // uuid
+  job_status?: "STARTED" | "PROCESSING" | "SUCCESS" | "FAILED"
+  message?: string
+  ics_output?: {
+    output_document?: {
+      filename?: { ... }
+      s3ref?: { ... }
+    }
+  }
+  pdf_output?: {
+    preview_url?: string
+    output_document?: {
+      filename?: { ... }
+      s3ref?: { ... }
+    }
+  }
+  docx_output?: {
+    preview_url?: string
+    output_document?: {
+      filename?: { ... }
+      s3ref?: { ... }
+    }
+  }
+  xlsx_output?: {
+    preview_url?: string
+    output_document?: {
+      filename?: { ... }
+      s3ref?: { ... }
+    }
+  }
+  error_output?: {
+    error_message?: string
+    error_code?: "PARSE_ERROR" | "DOC_TO_PDF_CONVERT_ERROR" | "INTERNAL_ERROR" | "INVALID_TEMPLATE_FORMAT"
+    error_details?: Array<{
+      explanation?: { ... }
+      context?: { ... }
+    }> | Array<{
+      items?: { ... }
+    }> | Array<{
+      id?: { ... }
+      context?: { ... }
+      explanation?: { ... }
+    }>
+  }
+  variable_payload?: {
+    additionalProperties?: string
+  }
+  template_settings?: {
+    custom_margins?: {
+      top?: { ... }
+      bottom?: { ... }
+    }
+    suggested_margins?: {
+      top?: { ... }
+      bottom?: { ... }
+    }
+    display_margin_guidelines?: boolean
+    enable_data_table_margin_autofix?: boolean
+    template_with_datatable?: boolean
+    enabled_template_settings_persistence?: boolean
+    misconfigured_margins?: boolean
+    file_entity_id?: string // uuid
+  }
+}
+```
+
+### `ConvertDocumentRequest`
+
+```ts
+type ConvertDocumentRequest = {
+  language?: string
+  input_document: {
+    s3ref: {
+      bucket: { ... }
+      key: { ... }
+    }
+  }
+  output_format: "pdf"
+  output_filename?: string
+}
+```
+
+### `ConvertDocumentResponse`
+
+```ts
+type ConvertDocumentResponse = {
+  output_document?: {
+    preview_url?: string
+    s3ref?: {
+      bucket: { ... }
+      key: { ... }
+    }
+  }
+}
+```