Uploads

(uploads)

Available Operations

abortMultipart - Abort multipart upload
batchPresignMultipartParts - Generates batches of presigned URLs for multipart parts
completeExternalUpload - Completes a direct external upload
completeMultipart - Complete multipart upload
createMultipartUpload - Creates a multipart external upload
createUpload - Creates an upload
generatePresignedPut - Initiates a direct external upload

abortMultipart

This endpoint aborts the multipart upload initiated with /create-multipart. This should be used when cancelling the upload. It does not matter if parts were already uploaded into the external storage provider.

You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See:

https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.

An external file store must be set up and enable_direct_s3_uploads must be set to true for this endpoint to function.

Example Usage

import { SDK } from "@lukehagar/discoursejs";

async function run() {
  const sdk = new SDK();

  const res = await sdk.uploads.abortMultipart({
    externalUploadIdentifier: "84x83tmxy398t3y._Q_z8CoJYVr69bE6D7f8J6Oo0434QquLFoYdGVerWFx9X5HDEI_TP_95c34n853495x35345394.d.ghQ",
  });

  if (res.statusCode == 200) {
    // handle response
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.AbortMultipartRequestBody	✔️	The request object to use for the request.
`config`	AxiosRequestConfig	➖	Available config options for making requests.

Response

Promise<operations.AbortMultipartResponse>

Errors

Error Object	Status Code	Content Type
errors.SDKError	4xx-5xx	/

batchPresignMultipartParts

Multipart uploads are uploaded in chunks or parts to individual presigned URLs, similar to the one generated by /generate-presigned-put. The part numbers provided must be between 1 and 10000. The total number of parts will depend on the chunk size in bytes that you intend to use to upload each chunk. For example a 12MB file may have 2 5MB chunks and a final 2MB chunk, for part numbers 1, 2, and 3.

This endpoint will return a presigned URL for each part number provided, which you can then use to send PUT requests for the binary chunk corresponding to that part. When the part is uploaded, the provider should return an ETag for the part, and this should be stored along with the part number, because this is needed to complete the multipart upload.

You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See:

https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.

An external file store must be set up and enable_direct_s3_uploads must be set to true for this endpoint to function.

Example Usage

import { SDK } from "@lukehagar/discoursejs";

async function run() {
  const sdk = new SDK();

  const res = await sdk.uploads.batchPresignMultipartParts({
    partNumbers: [
      1,
      2,
      3,
    ],
    uniqueIdentifier: "66e86218-80d9-4bda-b4d5-2b6def968705",
  });

  if (res.statusCode == 200) {
    // handle response
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.BatchPresignMultipartPartsRequestBody	✔️	The request object to use for the request.
`config`	AxiosRequestConfig	➖	Available config options for making requests.

Response

Promise<operations.BatchPresignMultipartPartsResponse>

Errors

Error Object	Status Code	Content Type
errors.SDKError	4xx-5xx	/

completeExternalUpload

Completes an external upload initialized with /get-presigned-put. The file will be moved from its temporary location in external storage to a final destination in the S3 bucket. An Upload record will also be created in the database in most cases.

If a sha1-checksum was provided in the initial request it will also be compared with the uploaded file in storage to make sure the same file was uploaded. The file size will be compared for the same reason.

You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See:

https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.

An external file store must be set up and enable_direct_s3_uploads must be set to true for this endpoint to function.

Example Usage

import { SDK } from "@lukehagar/discoursejs";

async function run() {
  const sdk = new SDK();

  const res = await sdk.uploads.completeExternalUpload({
    forPrivateMessage: "true",
    forSiteSetting: "true",
    pasted: "true",
    uniqueIdentifier: "66e86218-80d9-4bda-b4d5-2b6def968705",
  });

  if (res.statusCode == 200) {
    // handle response
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.CompleteExternalUploadRequestBody	✔️	The request object to use for the request.
`config`	AxiosRequestConfig	➖	Available config options for making requests.

Response

Promise<operations.CompleteExternalUploadResponse>

Errors

Error Object	Status Code	Content Type
errors.SDKError	4xx-5xx	/

completeMultipart

Completes the multipart upload in the external store, and copies the file from its temporary location to its final location in the store. All of the parts must have been uploaded to the external storage provider. An Upload record will be completed in most cases once the file is copied to its final location.

You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See:

https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.

An external file store must be set up and enable_direct_s3_uploads must be set to true for this endpoint to function.

Example Usage

import { SDK } from "@lukehagar/discoursejs";

async function run() {
  const sdk = new SDK();

  const res = await sdk.uploads.completeMultipart({
    parts: [
      "<value>",
      "<value>",
    ],
    uniqueIdentifier: "66e86218-80d9-4bda-b4d5-2b6def968705",
  });

  if (res.statusCode == 200) {
    // handle response
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.CompleteMultipartRequestBody	✔️	The request object to use for the request.
`config`	AxiosRequestConfig	➖	Available config options for making requests.

Response

Promise<operations.CompleteMultipartResponse>

Errors

Error Object	Status Code	Content Type
errors.SDKError	4xx-5xx	/

createMultipartUpload

Creates a multipart upload in the external storage provider, storing a temporary reference to the external upload similar to /get-presigned-put.

You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See:

https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.

An external file store must be set up and enable_direct_s3_uploads must be set to true for this endpoint to function.

Example Usage

import { SDK } from "@lukehagar/discoursejs";
import { UploadType } from "@lukehagar/discoursejs/dist/sdk/models/operations";

async function run() {
  const sdk = new SDK();

  const res = await sdk.uploads.createMultipartUpload({
    fileName: "IMG_2021.jpeg",
    fileSize: 4096,
    metadata: {},
    uploadType: UploadType.CardBackground,
  });

  if (res.statusCode == 200) {
    // handle response
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.CreateMultipartUploadRequestBody	✔️	The request object to use for the request.
`config`	AxiosRequestConfig	➖	Available config options for making requests.

Response

Promise<operations.CreateMultipartUploadResponse>

Errors

Error Object	Status Code	Content Type
errors.SDKError	4xx-5xx	/

createUpload

Creates an upload

Example Usage

import { SDK } from "@lukehagar/discoursejs";
import { TypeT } from "@lukehagar/discoursejs/dist/sdk/models/operations";

async function run() {
  const sdk = new SDK();

  const res = await sdk.uploads.createUpload({
    file: {
      content: new TextEncoder().encode("0x5d6beD2Fe2"),
      fileName: "blanche_centro_white.jpe",
    },
    type: TypeT.CardBackground,
  });

  if (res.statusCode == 200) {
    // handle response
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.CreateUploadRequestBody	✔️	The request object to use for the request.
`config`	AxiosRequestConfig	➖	Available config options for making requests.

Response

Promise<operations.CreateUploadResponse>

Errors

Error Object	Status Code	Content Type
errors.SDKError	4xx-5xx	/

generatePresignedPut

Direct external uploads bypass the usual method of creating uploads via the POST /uploads route, and upload directly to an external provider, which by default is S3. This route begins the process, and will return a unique identifier for the external upload as well as a presigned URL which is where the file binary blob should be uploaded to.

Once the upload is complete to the external service, you must call the POST /complete-external-upload route using the unique identifier returned by this route, which will create any required Upload record in the Discourse database and also move file from its temporary location to the final destination in the external storage service.

You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See:

https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.

An external file store must be set up and enable_direct_s3_uploads must be set to true for this endpoint to function.

Example Usage

import { SDK } from "@lukehagar/discoursejs";
import { GeneratePresignedPutType } from "@lukehagar/discoursejs/dist/sdk/models/operations";

async function run() {
  const sdk = new SDK();

  const res = await sdk.uploads.generatePresignedPut({
    fileName: "IMG_2021.jpeg",
    fileSize: 4096,
    metadata: {},
    type: GeneratePresignedPutType.CardBackground,
  });

  if (res.statusCode == 200) {
    // handle response
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.GeneratePresignedPutRequestBody	✔️	The request object to use for the request.
`config`	AxiosRequestConfig	➖	Available config options for making requests.

Response

Promise<operations.GeneratePresignedPutResponse>

Errors

Error Object	Status Code	Content Type
errors.SDKError	4xx-5xx	/

Files

README.md

Latest commit

History

README.md

File metadata and controls

Uploads

Available Operations

abortMultipart

Example Usage

Parameters

Response

Errors

batchPresignMultipartParts

Example Usage

Parameters

Response

Errors

completeExternalUpload

Example Usage

Parameters

Response

Errors

completeMultipart

Example Usage

Parameters

Response

Errors

createMultipartUpload

Example Usage

Parameters

Response

Errors

createUpload

Example Usage

Parameters

Response

Errors

generatePresignedPut

Example Usage

Parameters

Response

Errors