scaleway / scaleway-sdk-js

Integrate Scaleway with your JS application

Scaleway JS SDK

This SDK enables you to interact with Scaleway APIs.

Note The SDK works exclusively within a Node.js environment, as browser requests are limited by CORS restrictions.

🔗  Important links:

• Reference documentation
• Example projects
• Developers website (API documentation)

Getting Started

You'll need a pair of access and secret keys to connect to Scaleway API. Please check the documentation on how to retrieve them.

A minimal setup would look like this:

import { Registry, createClient } from '@scaleway/sdk'

const client = createClient({
  accessKey: 'SCWXXXXXXXXXXXXXXXXX',
  secretKey: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  defaultProjectId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  defaultRegion: 'fr-par',
  defaultZone: 'fr-par-1',
})

const api = new Registry.v1.API(client)

For a simpler setup, you could retrieve the profile from either the configuration file or the environment variables:

import { 
  loadProfileFromConfigurationFile, 
  // loadProfileFromEnvironmentValues,
} from '@scaleway/configuration-loader'

const profile = loadProfileFromConfigurationFile() // loadProfileFromEnvironmentValues()
const client = createClient(profile)

For more advanced needs, please check the examples.

Pagination

We included some pagination helpers for the methods supporting the feature. Let's take listNamespaces() (Registry product) as an example:

Retrieve the first page:

const namespaces = await api.listNamespaces(/*{ page: 1 }*/)

Retrieve all the pages:

const allNamespaces = await api.listNamespaces().all()

Iterate over the pages:

for await (const page of api.listNamespaces()) {
  // 
}

Types

The project is coded with Typescript, so don't hesitate to take advantage of it.

1. All types of a product are stored in the Product.version namespace. For instance, the Image interface of Registry v1 can be accessed with Registry.v1.Image.

2. We export errors in the namespace Errors, allowing you to differentiate the cases (e.g. Errors.PermissionsDeniedError).

Contributing Guidelines

This repository is at its early stage and is still in active development. If you are looking for a way to contribute please read CONTRIBUTING.md.

Reach us

We love feedback. Feel free to reach us on Scaleway Slack community, we are waiting for you on #opensource.

scaleway-sdk-js's Issues

Support for older Node versions

I tried creating a plugin for Strapi for using TEM as the email provider but it was rejected because Strapi supports Node 16 and requires plugins to do so as well. I can imagine this being the case for more frameworks so maybe it's better to support the previous LTS version as well as the current.

Improve locality type of an API

Context

At the moment, the locality object of an API (example with Instance) is only providing part of the information.

What information would be useful:

• API is zonal
• API is regional
• API is global (missing)
• API is missing its locality definition (missing)

Proposition

We could upgrade the object to this:

type ApiLocality = {
  type: 'zone'
  zones: Zone[]
} | {
  type: 'region'
  regions: Region[]
} | {
  type: 'global'
}

Which could lead to this object:

export class API extends ParentAPI {
  // Case 1: zone
  public static readonly LOCALITY: ApiLocality = { type: 'zone', zones: ['fr-par-1', 'fr-par-2'] }

  // Case 2: region
  public static readonly LOCALITY: ApiLocality = { type: 'region', regions: ['fr-par'] }

  // Case 3: global
  public static readonly LOCALITY: ApiLocality = { type: 'global' }

  // Case 4: not defined
}

Migration

Both objects would be supported for a period of time (the former one with a @deprecated).

List Scaleway configuration profiles

Why?

There is a need to be able to list all the profiles from the package configuration-loader.

Help Typescript detect that the required path parameter hasn’t been filed

Why?

The path parameter (e.g. locality like zone/region, or a resource ID) has a runtime check, however the typing currently cannot detect there is a missing value.

The idea would be to improve the SDK in order for Typescript to detect a parameter is missing.

Consider changing most Interface definitions to Type

Why?

There are subtiles differences between an Interface and a Type.

Currently we use interfaces in several scenarios:

• All entity definitions (e.g. Namespace), while we use type for all requests.
• Some definitions in the core client (e.g. Logger).

Using interface has some pros for the documentation. But if it's mostly a visual improvement, they it def should not be a key decision criteria.

Migrate from Lerna to Changesets

Example here.

Bonjour

Upgrade to Node 18 and drop cross-fetch

Why?

Version 18 is LTS. Plus it would allow to drop cross-fetch.

help cannot connect SSH

Hello, scaleway VM Cannot connect to SSH port 22, inboud open port 22

Set most requests enums as optional

Why?

By default a Protobuf enum will use the default (first) value if not defined.

However in an effort to improve DX, it was initially decided to:

• Have any enum as required
• But not order_by and similar fields (e.g. list requests)

However it seems to be counter productive in several scenarios, so the idea would be to:

• Have any enum as optional
• And mark them as required case by case (Protobuf side)

Add validation rules

Why?

Some fields are validated server side by specific rules.

It could make sense to have these rules in the SDK (e.g. same file as the transient statutes ?) in order to improve the DX.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Pending Status Checks

These updates await pending status checks. To force their creation now, click the checkbox below.

• chore(deps): update actions/checkout action to v4.1.6
• chore(deps): update dependency lerna to v8.1.3
• chore(deps): update codecov/codecov-action action to v4.4.0
• chore(deps): update dependency eslint to v9

Ignored or Blocked

These are blocked by an existing closed PR and will not be recreated unless you click a checkbox below.

• chore(deps): update node.js to >=14.21.3
• chore(deps): update node.js to v16
• chore(deps): update node.js to v18 (node, @types/node)
• chore(deps): update node.js to v20 (node, @types/node)

Detected dependencies

github-actions

.github/workflows/check-pull-request.yml

• actions/checkout v4.1.5
• pnpm/action-setup v4.0.0
• actions/setup-node v4.0.2
• ubuntu 22.04

.github/workflows/deploy-doc.yml

• actions/checkout v4
• pnpm/action-setup v4.0.0
• actions/setup-node v4
• actions/configure-pages v5
• actions/upload-pages-artifact v3
• actions/deploy-pages v4
• ubuntu 22.04

.github/workflows/deploy-package.yml

• actions/checkout v4.1.5
• pnpm/action-setup v4.0.0
• actions/setup-node v4.0.2
• ubuntu 22.04

.github/workflows/run-tests.yml

• actions/checkout v4.1.5
• pnpm/action-setup v4.0.0
• actions/setup-node v4.0.2
• actions/checkout v4.1.5
• pnpm/action-setup v4.0.0
• actions/setup-node v4.0.2
• actions/checkout v4.1.5
• pnpm/action-setup v4.0.0
• actions/setup-node v4.0.2
• codecov/codecov-action v4.3.1
• ubuntu 22.04
• ubuntu 22.04
• ubuntu 22.04

npm

examples/nodejs-minimal/package.json

• @types/node 20.11.19
• typescript 5.4.5

examples/serverless-function-minimal/package.json

• serverless-scaleway-functions 0.4.10
• @types/node 20.11.19
• typescript 5.4.5

package.json

• @commitlint/cli 19.3.0
• @commitlint/config-conventional 19.2.2
• @scaleway/eslint-config-react 3.18.2
• @vitest/coverage-istanbul 1.6.0
• @vitest/coverage-v8 1.6.0
• @vitest/ui 1.6.0
• babel-plugin-annotate-pure-calls 0.4.0
• browserslist 4.23.0
• cross-env 7.0.3
• cross-fetch 4.0.0
• cz-conventional-changelog 3.3.0
• esbuild-plugin-browserslist 0.11.1
• eslint-plugin-tsdoc 0.2.17
• eslint 8.57.0
• husky 9.0.11
• jsdom 24.0.0
• lerna 8.1.2
• lint-staged 15.2.2
• prettier 3.2.5
• read-pkg 9.0.1
• typedoc 0.25.13
• typescript 5.4.5
• vite 5.2.11
• vitest 1.6.0
• node >=18.0
• pnpm >=9.1.1
• pnpm 9.1.1

packages/clients/package.json

• @scaleway/random-name 5.1.0
• node >=18.0

packages/configuration-loader/package.json

• @types/node 18.11.18
• node >=14.13

---

• Check this box to trigger a request for Renovate to run again on this repository

Scaleway sdk with remix run leads to TypeError: Invalid response object

Hi everyone,

I encountered a bug with the Scaleway SDK for JavaScript. We are using your SDK in our Remix.run application to create or fetch tokens for accessing serverless containers.

Starting with version 0.1.0-beta35, all requests to Scaleway APIs are failing with the error "TypeError: Invalid response object."

The issue can be traced back to the following check in the index.cjs file:

const responseParser = (unmarshaller, responseType) => async response => {
  if (!(response instanceof Response)) {
    throw new TypeError('Invalid response object');
  }
  ....
}

However, the Response object is not unique within the Remix/React-Router context. They have encountered similar issues that can be found here:
related issue: remix-run/remix#4741
PRs to fix it:
remix-run/react-router#9690
remix-run/remix#4782

I suggest replacing the instanceof Response check with something like:

export function isResponse(value: any): value is Response {
  return (
    value != null &&
    typeof value.status === "number" &&
    typeof value.statusText === "string" &&
    typeof value.headers === "object" &&
    typeof value.body !== "undefined"
  );
}

We are currently stuck on version 0.1.0-beta34 until this issue is resolved. Please let me know if you have any further questions.

Add error interceptors for network calls

Why?

Be more flexible in the lifecycle of APIs calls.

Consider exporting API types one by one instead of global * export

Why?

Following this rule in scaleway-lib/eslint-config-react, it could be interesting to export types one by one in each API index file.

Currently we do export * from './types.gen'.

Things to consider:

• Should be achieved during generation
• We have to be able to add utils (manually written)
  • So change the main API class
  • And export more types / constants

Use Blob to manage files

Why?

Routes using a ScwFile was achieved as a quick way without linking to too many third-party libraries.

However if we bump to Node 18, it would allow us to use the Blob type more easily.

Things to consider:

• Download file with dl=1 mode and get a Blob.
• Upload file with Blob, but need a proper way to marshal for the expect type.

[TEM] Unable to set "reply to" address

Feature request

Ability to set the reply to address when creating an email:

api.createEmail({replyTo: "[email protected]"})

I'm not sure if this is a limitation of TEM or just the SDK. I cannot find anything about it in the docs.

Use case

For example when users submit a form which triggers an email to the admin. Instead of replying to the noreply address it would be better to reply to the email address provided in the form.