v3.0.0 Beta

[jacobbednarz]

Warning

v3.x of this library is a ground-up rewrite of the SDK, using code generation from our OpenAPI spec.

This package should be in a usable state for many projects, but expect frequent minor breaking
changes as we rename methods and types until GA. If this isn't suitable for you project, we recommend
pinning to the 2.x releases for now.

We're working on a new major version of our SDK and are excited to have you test it!

Please use this discussion page as a place to report issues and feedback about the new release.

Install

npm install [email protected]

Things we would like feedback on

• Endpoints that do not work despite existing in the SDK
• Types and error handling
• Major regressions from 2.x releases

[mhart]

Would love it if this was tree-shakeable! (ie, if you only want to talk to the workers API, then you should be able to bundle your JS app with only the files needed to do that)

[mhart]

Just for some inspiration about where this could go. Personally I'm all for keeping the one npm package, but just making it possible to use individual clients – and then these get shaked out by your bundler. ie, the AWS SDK v2 approach:

$ npm install aws-sdk

const S3 = require("aws-sdk/clients/S3");

const s3Client = new S3({});
await s3Client.createBucket(params);

The other approach is the AWS SDK v3 approach, which would mean an npm package per client/endpoint. I personally find this a bit much (for AWS that's 300+ npm packages) – the main argument for it is that it keeps your npm package small as well – but I don't think CF has anywhere near the same bloat as AWS, and it would mean a much larger burden on both maintaining/publishing all the individual packages, as well as a more complicated discovery aspect for users.

$ npm install @aws-sdk/client-s3

const { S3 } = require("@aws-sdk/client-s3");

const s3Client = new S3({});
await s3Client.createBucket(params);

[jacobbednarz]

this is a longer term task we're looking into, thanks!

[cpapazian]

I'm observing some minor type issues with the custom-hostname resource:

• custom_origin_server and custom_origin_sni only appear on CustomHostnameEditParams, but should be available on CustomHostnameCreateParams and all of the result available on all of the response types (i've confirmed that i'm able to pass custom_origin_server to a new record and that it shows up on the response, but haven't tested custom_origin_sni)
• status and verification_errors errors aren't available on response types

thanks!

[jasonkuhrt]

It appears that listing queues is not paginatable? What's up with that?

[jacobbednarz]

the pagination here (and hasNextPage being false) is a side effect of the backing service not correctly supporting pagination in the conventions we support and defaulting to pulling the first page of results. teams have tickets to address this and will improve with time as the SDKs mature however, it does look like this may have been fixed and just awaiting a release - https://github.com/cloudflare/cloudflare-typescript/pull/222/files#diff-b9378cad5f0837faa6a7ea9274c717ab343f62484ca124466b70579b036ae113R50.

for now, if you need it you could potentially pass a per_page option as part of the request parameters to the list operation or you could try the branch for the above PR to see if it works for you.

[jasonkuhrt]

@jacobbednarz if the release will be in the coming days I'm ok to wait.

[jasonkuhrt]

@jacobbednarz Is there a release cadence? Any ETA?

[jasonkuhrt]

@jacobbednarz I still don't understand how to paginate with 3.1.x. For example .getPaginatedItems() synchronously returns an array. That makes no sense. Could you share an example?

[HeyITGuyFixIt]

Still doesn't seem to work in 3.5.0. I am using it with Zero Trust Lists, trying to get the items in a list.

[annahassel]

I can’t find a method for editing stream videos, is it missing?

[jacobbednarz]

the API seems to want to use a POST which will be client.stream.create() which feels wrong. let me check with the service team to confirm how this is expected to work.

[jacobbednarz]

this is a legacy API so the above is how it exists today. the team will be working on adding it with a PUT so the SDK can support a .update() but you can use .create in the meantime and it will work the same.

[annahassel]

Sorry, I can't understand how to pass identifier to client.stream.create() to edit video details, can you help me? Should I use this._client to write own wrapper?

Query from API documentation:

Edit video details
POST https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/{identifier}

Source code:
https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/stream/stream.ts#L42-L61

[demosjarco]

Attempting to pass in the native global fetch from NodeJS 18+ is rejected by the types.

new Cloudflare({
	apiToken: process.env.["SOMETHING"],
	fetch,
});

error TS2322: Type '{ (input: RequestInfo | URL, init?: RequestInit | undefined): Promise<Response>; (input: string | Request | URL, init?: RequestInit | undefined): Promise<...>; }' is not assignable to type 'Fetch'.

[nicougou]

Hi !
I've been banging my head on walls during two days trying to use vecorize.indexes.upsert ^^

Method having a confusing signature

The method asks for a body, i would have expected that it is the object containing the vecotrs to upsert, but the object is actually un-used :

https://github.com/cloudflare/cloudflare-typescript/blob/54faa1bd35ae5f394e37e8ac7f75c36f738baff9/src/resources/vectorize/indexes.ts#L161C1-L173C4

The special case of application/x-ndjson

This endpoint is somehow special since it uses a application/x-ndjson body.

I managed to figure out the correct signature :

const response = await this.cloudflare.vectorize.indexes.upsert("{{accountId}}", "{{indexName}}", {}, {
  body: {
    body: memoryVectors,
  },
  headers: {
    'Content-Type': 'application/x-ndjson',
  },
})

But next i kept having consistently this error: [{"code":1006,"message":"vectorize.invalid_body_payload"}]

While the same implementation using fetch worked :

const request = await fetch(`https://api.cloudflare.com/client/v4/accounts/{{accountId}}/vectorize/indexes/{{indexName}}/upsert`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-ndjson',
    'Authorization': `Bearer {{apiKey}}`,
  },
  body: memoryVectors,
})

The workaround

I found a potential cause, or at least workaround for this.
application/x-ndjson is special because it is a \n separated string.

In core.ts you have this :

cloudflare-typescript/src/core.ts

Lines 268 to 272 in 54faa1b

	const body =
	isMultipartBody(options.body) ? options.body.body
	: options.body ? JSON.stringify(options.body, null, 2)
	: null;
	const contentLength = this.calculateContentLength(body);

It actually re-transforms the payload body using JSON.stringify(options.body, null, 2), making my initial body (that works with fetch) invalid.

So i checked isMultipartBody, to see how i could leverage it to fall into this condition and avoid my body being transformed.

I ended with this :

const response = await this.cloudflare.vectorize.indexes.upsert("{{accountId}}", "{{indexName}}", {}, {
  body: {
    body: memoryVectors,
    get [Symbol.toStringTag]() {
      return 'MultipartBody'
    },
  },
  headers: {
    'Content-Type': 'application/x-ndjson',
  },
})

Messing with my initial body tricks the core.ts code to treat it as a multipart body, and not transforming it.

Conclusion

I have no idea if this should be considered a bug, a misuse of the sdk on my end, or lack of documentation.

If you have any feedback on this, i'm available for more details :)

[lifeiscontent]

cloudflare.images.v1.create() does not allow passing metadata or requireSignedURLs as documented here: https://developers.cloudflare.com/api/operations/cloudflare-images-upload-an-image-via-url

[jacobbednarz]

what version are you using? can you provide a minimal reproduction case for when you hit this error?

[lifeiscontent]

the @ts-expect-error should not be necessary

import Client from "cloudflare";
// context comes from loadContext in remix
const client = new Client({
      apiToken: context.cloudflare.env.CLOUDFLARE_API_KEY,
})
const image = await client.images.v1.create(
        {
          // @ts-expect-error - `requireSignedURLs` is not in the type definition
          requireSignedURLs: true,
          metadata: JSON.stringify({
            userId: user.id,
          }),
          file: submission.value.file,
          account_id: context.cloudflare.env.CLOUDFLARE_ACCOUNT_ID,
        },
        {
        // not sure if this was necessary, but this is just from proof of concept code
          headers: {
            Authorization: `Bearer ${context.cloudflare.env.CLOUDFLARE_API_KEY}`,
          },
        }
      );
      ```

[jacobbednarz]

you definitely don't need the authorization HTTP header that is handled in the initialiser.

[jacobbednarz]

requireSignedURLs is in the Image definition however, it is not present in the V1CreateParams.

[lifeiscontent]

yep, I'm aware, I am patching the package currently in the repo I'm using it, the value itself does work when being passed through to the body

[fshafiee]

Hi there,

I’m currently trying to migrate our Cloudflare integration to this package. However, right now, our blocker is the custom hostname API response type. It’s severely lacking in v3.0.0, but I see the issue being fixed in v3.1.0. I am specifically referring to the Hostname status as highlighted in the Custom Hostname docs

Before your customer does this step, confirm that the hostname’s Certificate status and Hostname status are both Active.

Here’s the API Reference:
https://developers.cloudflare.com/api/operations/custom-hostname-for-a-zone-custom-hostname-details

The release seemed imminent at the time, so I put a lid on it, but seeing that there has been no maintainer activity on the new release and after receiving no response on my previous inquiries, I thought I'd raise the issue here for clarification before moving forward with a custom patch. Is there an ETA for v3.1.0?

[demosjarco]

Hey, I see that the Analytics engine endpoints are missing

[jacobbednarz]

the endpoints are not publicly documented in our API schemas so they will not be supported.

if you'd like to see them added, please open a support ticket requesting it or have your account team raise a request.

in the meantime, you can use the HTTP verb on the client directly (client.get) to fetch any API endpoint (even undocumented).

resp = await client.get("/foo/bar")

thanks!

[reginsmol]

Direct Uploads do not correctly parse the params into a multipart form body.

NodeJS: v21.7.3
Cloudflare Package: v3.2.0

const Cloudflare = require('cloudflare').Cloudflare

const client = new Cloudflare({
    apiToken: process.env.token
})

client.images.v2.directUploads.create({
    account_id: process.env.accountId,
    requireSignedUrls: false,
    metadata: {
        foo: 'bar'
    }
})

BadRequestError: 400 {"result":null,"success":false,"errors":[{"code":5400,"message":"Bad request: Error parsing form fields"}],"messages":[]}

[reginsmol]

TUS Upload returns no information. Looks like its because there is no response body and the data is sent in the headers.

Node v20.13.1
Cloudflare Package v3.2.0

const Cloudflare = require('cloudflare').Cloudflare

const client = new Cloudflare({
    apiToken: process.env.token
})

client.stream.create({
    account_id: process.env.accountId,
    maxDurationSeconds: 1000,
    'Tus-Resumable': '1.0.0',
    'Upload-Length': 10000
}).then(result => {
    console.log(result)
})

[naegelin]

@jacobbednarz What happened to WorkerRoutes from 3.0.0 to 3.1.0/3.2.0? Are they renamed or has the functionality moved outside of workers ?

[mizchi]

I can't send vectorize.indexes.insert.

v3.2.0

According to the documentation, it is necessary to send Content-Type: application/x-ndjson, but there does not appear to be a mechanism for sending ndjson in this client.

https://developers.cloudflare.com/api/operations/vectorize-insert-vector

This code does not work.

import Cloudflare from "cloudflare";
const cf = new Cloudflare({ apiToken: 'my-token'});
const vectors: VectorizeVector[] = [{
  id: '1',
  values: [0, 0, 1]
}]
await cf.vectorize.indexes.insert("my-embeddings-index", {
  account_id:  'my-id',
  body: vectors.map((vector) => JSON.stringify(vector)).join('\n'),
});
// error: Uncaught (in promise) Error: 400 {"result":null,"success":false,"errors":[{"code":1005,"message":"vectorize.unknown_content_type"}],"messages":[]}

Overriding headers or body with a third argument did not work.

My work around

Fetching direct is here

https://gist.github.com/mizchi/95fe46c39a2a6248eca3d3035567ef27#file-run-cfai-ts-L36-L51

[scottambroseio]

v3.2.0

Auth credentials are required for the IP list api in order to pass validation when that specific api doesn't require auth.

const Cloudflare = require('cloudflare')

async function main() {
    const cloudflare = new Cloudflare()

    console.log(await cloudflare.ips.list())
}

main()

produces the following error

        throw new Error('Could not resolve authentication method. Expected one of apiEmail, apiKey, apiToken or userServiceKey to be set. Or for one of the "X-Auth-Email", "X-Auth-Key", "Authorization" or "X-Auth-User-Service-Key" headers to be explicitly omitted');
              ^

Error: Could not resolve authentication method. Expected one of apiEmail, apiKey, apiToken or userServiceKey to be set. Or for one of the "X-Auth-Email", "X-Auth-Key", "Authorization" or "X-Auth-User-Service-Key" headers to be explicitly omitted

Workaround

const Cloudflare = require('cloudflare')

async function main() {
    const cloudflare = new Cloudflare({
        apiToken: 'dummy_value'
    })

    console.log(await cloudflare.ips.list())
}

main()

works and prints out the IP ranges.

When calling additional APIs that require a token, setting a real token on the client will naturally avoid this issue. For use cases where this is the only API being called however, using a real token leads to having an additional token to secure and manage which isn't ideal when the token is unnecessary.

The equivalent functionality in the SDK for go https://pkg.go.dev/github.com/cloudflare/cloudflare-go#IPs doesn't require credentials and will work without any credential values being set

package main

import (
	"log"
	"github.com/cloudflare/cloudflare-go"
)

func main() {
	ranges, err := cloudflare.IPs()

	if err != nil {
		log.Fatalln(err)
	}

	log.Println(ranges)
}

[jacobbednarz]

this is intentional as it is the only endpoint that does not require auth.

all the new SDKs enforce this, including Go. the example you've shown here is the legacy library.

[sandro-pasquali]

Hi!

Upgraded to v3. It seems the response signature for cache purging has changed.

Using the previous (2.x) client, purging files was done via [client].zones.purgeCache(zoneId, { files });.

This returned a response as detailed here: https://developers.cloudflare.com/api/operations/zone-purge

{
  "errors": [],
  "messages": [],
  "success": true,
  "result": {
    "id": "023e105f4ecef4dc9ca31a8372d0c353"
  }
}

For V3 purging works using: [client].cache.purge({ zone_id, files })

However the response is, on success:

{
    "id": "023e105f4ecef4dc9ca31a8372d0c353"
}

And simply null on error.

I was wondering if this is a permanent change? Or perhaps I need to do something else to get richer responses? It was useful to have proper error messages.

Thanks!

[jacobbednarz]

the API response is still the same however, we unwrap it for usage in the SDK. yes - the handling will stay that way going forward as we now have better practices built in.

for error handling, you should check out the "handling errors" section of the README.md to use proper handling (like catching/using the custom error types)

if you want the raw response, the README also includes ways of getting it (either with the helper method or by using the method helpers like .post()).

[sandro-pasquali]

Hi!

I'm using cloudflare(v3) in an AWS Lambda deployment. I'm seeing this error:

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/var/task/node_modules/cloudflare/resources/zero-trust/dex/tests/tests.mjs' imported from /var/task/node_modules/cloudflare/resources/zero-trust/dex/dex.mjs
    at finalizeResolution (node:internal/modules/esm/resolve:269:11)
    at moduleResolve (node:internal/modules/esm/resolve:937:10)
    at moduleResolveWithNodePath (node:internal/modules/esm/resolve:1161:14)
    at defaultResolve (node:internal/modules/esm/resolve:1204:79)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:383:12)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:352:25)
    at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:227:38)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:87:39)
    at link (node:internal/modules/esm/module_job:86:36) {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///var/task/node_modules/cloudflare/resources/zero-trust/dex/tests/tests.mjs'
}

The application bundled for Lambda is of type: "module", if that matters.

v2 did not have this problem.

Thanks!

[timk153]

Hi there,

This is a bug report.
I'm unable to filter DNS records when using the list command.

Steps to replicate:

Invoke the dns records list API, filtering based on a comment:

const paginatedResult = await this.cloudFlare.dns.records.list({
  zone_id: zoneId,
  comment: {
    exact: 'some-comment-here',
  },
});

The resulting query string is constructed as follows: '?comment%5Bexact%5D=some-comment-here'.
Having decoded this, it's equivalent to '?comment[exact]=some-comment-here'.
Both of which aren't understood by the list API endpoint.

Root cause

This issue surrounds how qs.stringify is consumed within index.ts.
It's not configured to use dot notation, despite this being how query string parameters for CloudFlare API are expected.

The line causing this behaviour is here:

cloudflare-typescript/src/index.ts

Line 331 in bfebf03

return qs.stringify(query, { arrayFormat: 'repeat' });

Fix

Amending this line to the following fixes the issue:

return qs.stringify(query, { allowDots: true });

Allow dots will output the object structure used to construct queries using a dot notation.
Using the example above, the output becomes: '?comment.exact=some-comment-here'
Which successfully returns the filtered DNS records.

I suspect this behaviour is common to other parameters constructed in this manner, so is likely to fix many occurrences.
Hopefully this will be trivial to incorporate into your code generation without any regression.

[jacobbednarz]

this is already fixed and will be a part of the next release. in the meantime, you can checkout the branch at #1020 for the fix.

[mldangelo]

Hi @jacobbednarz, this is a bug report as well. I'm filing here because I am unable to file a new issue.

I believe there was an incorrect rename of TextGeneration to Variant7 in commit ca651fccbb75558512cce645105ae4c0c830fbb6. This change broke my build as I am using this type and it prevents me from upgrading.

Could you please confirm if this rename was intentional? If not, can you revert this change or provide guidance on how to handle this in the latest release?

Thanks!

[mlafeldt]

Hey,

I wonder why neither the API docs at https://developers.cloudflare.com nor this library include R2 object operations such as list, get, put, and delete. They do exist and are being used by wrangler.

Example to list objects in a bucket:

curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/r2/buckets/$BUCKET/objects?per_page=1000

[janwilmake]

This is not so much a feedback for the typescript SDK but more for the OpenAPI in general, as this endpoint isn't documented:

POST https://api.cloudflare.com/client/v4/accounts/${cloudflareAccountId}/workers/services/${workerName}/environments/production/subdomain

I assume it will therefore also not show up in the ts sdk or any other. I had to reverse engineer this from the dashboard.

Couldn't find where to submit this issue.

[JohnnyMcGee]

SDK Type does not match Stream API Response

Hello everyone! I'm having an issue where the Cloudflare Stream API response type does not match the defined Typescript type in the SDK. This means I cannot rely on the SDK type and have to override it to consume the API response.

• SDK Version: 3.5.0
• API Endpoint: /accounts/{account_id}/stream/live_inputs/{live_input_identifier}

My Code:

const cloudflare = new Cloudflare({
    apiToken: CLOUDFLARE_API_TOKEN,
});
const liveInput = await cloudflare.stream.liveInputs.get(liveInputId, {
    account_id: CLOUDFLARE_ACCOUNT_ID,
});

The SDK response type:

The SDK expects status to be one of these string values.

/**
 * Details about a live input.
 */
export interface LiveInput {
//  ... other interface fields

  /**
   * The connection status of a live input.
   */
  status?:
    | 'connected'
    | 'reconnected'
    | 'reconnecting'
    | 'client_disconnect'
    | 'ttl_exceeded'
    | 'failed_to_connect'
    | 'failed_to_reconnect'
    | 'new_configuration_accepted'
    | null;
}

The actual API Response:

The API returns an object type for status.

{
  // ...Other response fields

  status: {
  current: {
    ingestProtocol: 'rtmp',
    reason: 'client_disconnect',
    state: 'disconnected',
    statusEnteredAt: '2024-10-11T23:25:41.470Z',
    statusLastSeen: '2024-10-11T23:25:41.470Z'
  },
  history: [
    {
      ingestProtocol: 'rtmp',
      reason: 'connected',
      state: 'connected',
      statusEnteredAt: '2024-10-11T23:24:40.901Z'
    }
  ]
}
}

As you can see, the API response does not match the SDK type. Is this something I can fix in my SDK configuration? Or are the SDK types just wrong? Thanks!