@docusign/iam-sdk

/* * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT. */ import { agreementManagerBulkJobCreateBulkUploadJob } from "../funcs/agreementManagerBulkJobCreateBulkUploadJob.js"; import { agreementManagerBulkJobGetBulkJobStatus } from "../funcs/agreementManagerBulkJobGetBulkJobStatus.js"; import { agreementManagerBulkJobUploadCompleteBulkJob } from "../funcs/agreementManagerBulkJobUploadCompleteBulkJob.js"; import { ClientSDK, RequestOptions } from "../lib/sdks.js"; import * as components from "../models/components/index.js"; import * as operations from "../models/operations/index.js"; import { unwrapAsync } from "../types/fp.js"; export class BulkJob extends ClientSDK { /** * Create new bulk job with presigned URLs direct to Azure Blob Store * * @remarks * Create a new job, give presigned URLs back, the client will upload to Azure Blob Store directly. * * **Important Upload Workflow**: * 1. Call this endpoint to create a job and receive upload URLs * 2. For each document in the response's `_embedded.documents` array, extract the `upload_document` URL from `_actions` * 3. Upload your document file to each URL using an HTTP PUT request with the document content as binary data * 4. After all documents are uploaded, call the `/actions/complete` endpoint to finalize the job * 5. Use the GET endpoint to monitor job progress * * **Example response structure**: * ```json * { * "_embedded": { * "documents": [ * { * "id": "8c566d26-e7fb-4b7e-870c-1d0fb8df9084", * "sequence": 1, * "_actions": { * "upload_document": "https://docupstoragewestwu3dsto.blob.core.windows.net/..." * } * } * ] * } * } * ``` * * **Azure Blob Storage Upload Instructions**: * * Use the pre-signed URL from step 2 to upload your document directly to Azure Blob Storage: * * ``` * PUT [pre-signed URL from _actions.upload_document] * * Headers: * - x-ms-blob-type: BlockBlob (Required) * - x-ms-meta-filename: YourDocumentName.pdf (Recommended) * - Content-Type: application/pdf (Required) * - x-ms-meta-metadata: <stringified JSON metadata> (Optional) * * Body: [Your document binary data] * ``` * * **Important Notes**: * - The `upload_document` URLs are pre-signed Azure Blob Storage URLs with time-limited validity (8 hours) * - No Auth header is needed * - The `x-ms-meta-filename` header should contain your original document filename * - The `x-ms-blob-type` must be set to `BlockBlob` * - Setting the `Content-Type` header is recommended to match your document type * - If `Content-Type` is not specified, Azure defaults to `application/octet-stream` * - The `x-ms-meta-metadata` header is optional and allows you to attach metadata to the newly created agreement at upload time. See **Applying Metadata to Agreements** below for details * * **Applying Metadata to Agreements**: * * You may include metadata alongside the document bytes during upload. This metadata will be directly applied to the * newly created agreement. To do this, include the `x-ms-meta-metadata` header on the PUT operation with a stringified * JSON value. * * The JSON schema for this header follows the same structure as the standard Agreement PATCH request body. * * **Example metadata JSON**: * ```json * { * "provisions": { * "jurisdiction": "California", * "payment_terms_due_date": "OTHER" * }, * "custom_provisions": { * "c_ClientId": "value" * }, * "linked_data": [ * { * "application_name": "Salesforce", * "object_name": "Account", * "record_id": "579386BF-C8EA-4673-AE0E-E2F922B09DC5" * }, * { * "application_name": "Dynamics", * "object_name": "Account", * "record_id": "514CEAFB-1AC7-43FF-9E88-24CB15150963" * } * ] * } * ``` * * **Stringified header value**: * * The JSON must be stringified before being set as the header value. For example, the above JSON would become: * ``` * x-ms-meta-metadata: "{\"provisions\":{\"jurisdiction\":\"California\",\"payment_terms_due_date\":\"OTHER\"},\"custom_provisions\":{\"c_ClientId\":\"value\"},\"linked_data\":[{\"application_name\":\"Salesforce\",\"object_name\":\"Account\",\"record_id\":\"579386BF-C8EA-4673-AE0E-E2F922B09DC5\"},{\"application_name\":\"Dynamics\",\"object_name\":\"Account\",\"record_id\":\"514CEAFB-1AC7-43FF-9E88-24CB15150963\"}]}" * ``` * * **Metadata Notes**: * - The `x-ms-meta-metadata` header is entirely optional. If omitted, the agreement is created with AI-extracted values only * - The JSON must be stringified (serialized to a single string) before being placed in the header value * - The metadata payload follows the same schema as the Agreement PATCH endpoint request body * - Values provided via metadata will be applied to the agreement after creation, overriding any AI-extracted values for the same fields * * **Firewall & Network Configuration**: * * If your organization uses firewalls or network restrictions, you may need to whitelist the following Azure Blob Storage domains * to ensure successful document uploads. The upload URLs returned by this API will use one of these domains based on your * account's geographic region: * * **Primary Storage Endpoints**: * - `https://docupstorageaustauepsto.blob.core.windows.net/` * - `https://docupstoragecanacacpsto.blob.core.windows.net/` * - `https://docupstoragecentcuspsto.blob.core.windows.net/` * - `https://docupstorageeasteu2psto.blob.core.windows.net/` * - `https://docupstorageeasteusdsto.blob.core.windows.net/` (Demo) * - `https://docupstoragejapajpepsto.blob.core.windows.net/` * - `https://docupstoragenortneupsto.blob.core.windows.net/` * - `https://docupstoragewestweupsto.blob.core.windows.net/` * - `https://docupstoragewestwu3dsto.blob.core.windows.net/` (Demo) * * **Secondary Storage Endpoints** (for redundancy/failover): * - `https://docupstorageaustauepsto-secondary.blob.core.windows.net/` * - `https://docupstoragecanacacpsto-secondary.blob.core.windows.net/` * - `https://docupstoragecentcuspsto-secondary.blob.core.windows.net/` * - `https://docupstorageeasteu2psto-secondary.blob.core.windows.net/` * - `https://docupstorageeasteusdsto-secondary.blob.core.windows.net/` (Demo) * - `https://docupstoragejapajpepsto-secondary.blob.core.windows.net/` * - `https://docupstoragenortneupsto-secondary.blob.core.windows.net/` * - `https://docupstoragewestweupsto-secondary.blob.core.windows.net/` * - `https://docupstoragewestwu3dsto-secondary.blob.core.windows.net/` (Demo) * * **Note**: You may whitelist all domains listed above, or contact your DocuSign administrator to determine which specific * region(s) your account uses to minimize the whitelist scope. * * **Supported File Formats & Content Types**: * * The table below shows common file formats and their recommended Content-Type headers. * **Note**: For the most up-to-date list of supported formats, headers, and constraints, always refer to the * `_action_templates` object in the API response, which provides dynamic configuration including: * - `allowed_formats`: Current list of supported file extensions * - `headers`: Required HTTP headers with examples * - `constraints`: Maximum file size and other limits * - `success_status_code`: Expected response code for successful uploads * * | Format | Extension | Content-Type | * |--------|-----------|--------------| * | PDF | .pdf | `application/pdf` | * | Word Document (2007+) | .docx | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | * | Word Document (Legacy) | .doc | `application/msword` | * | PowerPoint Presentation (2007+) | .pptx | `application/vnd.openxmlformats-officedocument.presentationml.presentation` | * | PowerPoint Presentation (Legacy) | .ppt | `application/vnd.ms-powerpoint` | * | PowerPoint Slideshow | .ppsx | `application/vnd.openxmlformats-officedocument.presentationml.slideshow` | * | Excel Workbook (2007+) | .xlsx | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | * | Excel Workbook (Legacy) | .xls | `application/vnd.ms-excel` | * | Excel Binary Workbook | .xlsb | `application/vnd.ms-excel.sheet.binary.macroenabled.12` | * | Rich Text Format | .rtf | `text/rtf` | * | WordPerfect Document | .wpd | `application/vnd.wordperfect` | * | HTML | .html, .htm | `text/html` | * | JPEG Image | .jpg, .jpeg | `image/jpeg` | * | PNG Image | .png | `image/png` | * | TIFF Image | .tif, .tiff | `image/tiff` | * * **Example Upload Requests**: * * PDF Document (with optional metadata): * ``` * PUT https://storage.blob.core.windows.net/container/doc-id?signature=... * Content-Type: application/pdf * x-ms-blob-type: BlockBlob * x-ms-meta-filename: contract.pdf * x-ms-meta-metadata: "{\"provisions\":{\"jurisdiction\":\"California\"},\"custom_provisions\":{\"c_ClientId\":\"value\"}}" * * [Binary PDF data] * ``` * * Word Document: * ``` * PUT https://storage.blob.core.windows.net/container/doc-id?signature=... * Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document * x-ms-blob-type: BlockBlob * x-ms-meta-filename: agreement.docx * * [Binary DOCX data] * ``` * * Image: * ``` * PUT https://storage.blob.core.windows.net/container/doc-id?signature=... * Content-Type: image/jpeg * x-ms-blob-type: BlockBlob * x-ms-meta-filename: signed-page.jpg * * [Binary JPEG data] * ``` */ async createBulkUploadJob( request: operations.CreateBulkUploadJobRequest, options?: RequestOptions, ): Promise<components.BulkJob> { return unwrapAsync(agreementManagerBulkJobCreateBulkUploadJob( this, request, options, )); } /** * Get bulk job status * * @remarks * Get the current status and details of a bulk job. */ async getBulkJobStatus( request: operations.GetBulkJobStatusRequest, options?: RequestOptions, ): Promise<components.BulkJob> { return unwrapAsync(agreementManagerBulkJobGetBulkJobStatus( this, request, options, )); } /** * Mark bulk job upload as complete * * @remarks * Mark the upload of documents as complete for a bulk job. * End user won't upload more docs for this job. * * **Important**: Only call this endpoint after successfully uploading all documents to their respective pre-signed URLs obtained from the create job response. */ async uploadCompleteBulkJob( request: operations.UploadCompleteBulkJobRequest, options?: RequestOptions, ): Promise<components.BulkJob> { return unwrapAsync(agreementManagerBulkJobUploadCompleteBulkJob( this, request, options, )); } }