TypeScript: How to set the data parameter to Buffer

[retorquere]

How must I upload binary release assets using the v17 api? The typings say data must be a string, but I need to upload a zip file. If I give it data: fs.readFileSync(filename).toString(), the resulting release asset looks like a zipfile but it's corrupt.

[retorquere]

It looks like the data parameter to uploadReleaseAsset must be string | Buffer, not string, but I don't know where the code lives so I can't put together a PR. For the time being, this works:

await octokit.repos.uploadReleaseAsset({
      owner,
      repo,
      url: release.data.upload_url,
      release_id: release.data.id,
      data: (fs.readFileSync(asset) as unknown as string), // fool octokit into accepting the Buffer
      headers: {
        'content-type': contentType,
        'content-length': fs.statSync(asset).size,
      },
      name,
    })

[gr2m]

Thanks for opening the issue and the update. Sounds like the typing is off. The code lives at https://github.com/octokit/plugin-rest-endpoint-methods.js/. The types for the endpoint methods are generated here: https://github.com/octokit/plugin-rest-endpoint-methods.js/blob/master/scripts/update-endpoints/types.js

The "Upload a release asset" is a special case endpoint. For example, it's the only one with a parameter that can be either string or buffer. We might need to implement a workaround for that endpoint explicitly. We already have a workaround in there: https://github.com/octokit/plugin-rest-endpoint-methods.js/blob/96ca2f85ab845b9a09e8be2357d3f6a8a6b55d80/scripts/update-endpoints/types.js#L347-L351

To give you a quick run down how these methods are generated:

1. https://github.com/octokit/routes/ runs an hourly cron job which scrapes the docs at developer.github.com/v3/ and turns them into a JSON API spec
2. Whenever an update is found, a pull request is created. Once merged, a release is created and all repositories that use the JSON API are specified.
3. For https://github.com/octokit/plugin-rest-endpoint-methods.js/, it's update workflow is triggered, which runs VERSION=1.2.3 npm run update-endpoints where 1.2.3 is the latest version of octokit/routes (without the v prefix)

[jan-auer]

v16 and before just used string | object. Just to not throw people off when passing a buffer in, would that be an acceptable workaround?

[retorquere]

That looks a bit scary. I can confirm though that (fs.readFileSync(asset) as unknown as string) does work.

[gr2m]

I'm not sure if we will be able to address this, because Buffer only exists in Node, but the types are used also by code run in Browsers and Deno. We would need to add a manual workaround when generating the types, which might be possible, but I'm unsure at this point.

I'm glad the as unknown as Buffer workaround works for you for the time being. I'll leave the issue open, I'll get back to it eventually

[davidwinter]

This worked for me as well. As an interim, could we at least update the documentation, or add a caveat to the top-level READMEthat explains this workaround?

[BYK]

I see no activity on this issue since August and there isn't even a warning which is dangerous. We recently upgraded Octokit and this typing mismatch caused a major issue at Sentry: getsentry/craft#302

Anything we an help to expedite a solution, if not a big big warning?

[gr2m]

we would likely need to address this in GitHub's official OpenAPI spec.

The current specification for the repos/upload-release-asset operation is

      "post": {
        "summary": "Upload a release asset",
        "description": "This endpoint makes use of [a Hypermedia relation](https://docs.github.com/rest/overview/resources-in-the-rest-api#hypermedia) to determine which URL to access. The endpoint you call to upload release assets is specific to your release. Use the `upload_url` returned in\nthe response of the [Create a release endpoint](https://docs.github.com/rest/reference/repos#create-a-release) to upload a release asset.\n\nYou need to use an HTTP client which supports [SNI](http://en.wikipedia.org/wiki/Server_Name_Indication) to make calls to this endpoint.\n\nMost libraries will set the required `Content-Length` header automatically. Use the required `Content-Type` header to provide the media type of the asset. For a list of media types, see [Media Types](https://www.iana.org/assignments/media-types/media-types.xhtml). For example: \n\n`application/zip`\n\nGitHub expects the asset data in its raw binary form, rather than JSON. You will send the raw binary content of the asset as the request body. Everything else about the endpoint is the same as the rest of the API. For example,\nyou'll still need to pass your authentication to be able to upload an asset.\n\nWhen an upstream failure occurs, you will receive a `502 Bad Gateway` status. This may leave an empty asset with a state of `starter`. It can be safely deleted.\n\n**Notes:**\n*   GitHub renames asset filenames that have special characters, non-alphanumeric characters, and leading or trailing periods. The \"[List assets for a release](https://docs.github.com/rest/reference/repos#list-assets-for-a-release)\"\nendpoint lists the renamed filenames. For more information and help, contact [GitHub Support](https://support.github.com/contact?tags=dotcom-rest-api).\n*   If you upload an asset with the same filename as another uploaded asset, you'll receive an error and must delete the old file before you can re-upload the new asset.",
        "tags": ["repos"],
        "operationId": "repos/upload-release-asset",
        "externalDocs": {
          "description": "API method documentation",
          "url": "https://docs.github.com/rest/reference/repos#upload-a-release-asset"
        },
        "servers": [
          {
            "url": "{origin}",
            "variables": {
              "origin": {
                "default": "https://uploads.github.com",
                "description": "The URL origin (protocol + host name + port) is included in `upload_url` returned in the response of the \"Create a release\" endpoint"
              }
            }
          }
        ],
        "parameters": [
          { "$ref": "#/components/parameters/owner" },
          { "$ref": "#/components/parameters/repo" },
          { "$ref": "#/components/parameters/release-id" },
          {
            "name": "name",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          },
          { "name": "label", "in": "query", "schema": { "type": "string" } }
        ],
        "requestBody": {
          "content": {
            "*/*": {
              "schema": { "type": "string", "description": "The raw file data" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Response for successful upload",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/release-asset" },
                "examples": {
                  "response-for-successful-upload": {
                    "$ref": "#/components/examples/release-asset-response-for-successful-upload"
                  }
                }
              }
            }
          }
        },
        "x-github": {
          "githubCloudOnly": false,
          "enabledForGitHubApps": true,
          "previews": [],
          "category": "repos",
          "subcategory": "releases"
        },
        "x-octokit": {}
      }

The relevant bit is

  "schema": { "type": "string", "description": "The raw file data" }

This is JSON Schema. Maybe there is a better value for type than string?

I did a quick search and found type: string, format: binary. Maybe the solution would be an anyOf array, with the current item as is, and one with the format: binary added.

GitHub is current preparing to upgrade to OpenAPI spec 3.1 though, and if I recall correctly the format key will no longer be supported.

If you like you can file an issue at https://github.com/github/rest-api-description/ for further discussion, make sure none has been filed yet

When the schema was addressed in the OpenAPI spec, we need to make sure that it's correctly transpiled to TypeScript types via https://github.com/octokit/openapi-types.ts, which is using https://github.com/drwpow/openapi-typescript

[gr2m]

As an alternative, we could remove this endpoint entirely from the auto-generated types and do it by hand, or add a manual overwrite. It's such an obscure endpoint in comparison to the others it might be the best approach