Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dynabloxjs/dynablox_opencloud
A Roblox OpenCloud API wrapper for Deno and NodeJS written in TypeScript.
https://github.com/dynabloxjs/dynablox_opencloud
api deno dynablox nodejs opencloud rbx roblox roblox-api roblox-dev
Last synced: about 2 months ago
JSON representation
A Roblox OpenCloud API wrapper for Deno and NodeJS written in TypeScript.
- Host: GitHub
- URL: https://github.com/dynabloxjs/dynablox_opencloud
- Owner: dynabloxjs
- License: mit
- Archived: true
- Created: 2022-03-29T01:41:13.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2022-12-18T06:17:39.000Z (almost 2 years ago)
- Last Synced: 2024-10-19T04:09:22.618Z (about 2 months ago)
- Topics: api, deno, dynablox, nodejs, opencloud, rbx, roblox, roblox-api, roblox-dev
- Language: TypeScript
- Homepage:
- Size: 302 KB
- Stars: 12
- Watchers: 0
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-roblox - Dynablox Opencloud
README
> ### Active Development
> This module is currently in the initial development phase. Breaking changes may be introduced without warning before a stable 1.0.0 release. Check release notes of every release before updating.
###
dynablox opencloud
docs
| deno.land/x
| npm
| release notes
An API wrapper for the OpenCloud Roblox API built using the Deno runtime, with support for NodeJS via transpilation.
* **Compatible**: Built in TypeScript using Deno. Supported in NodeJS as a ES and CommonJS module via transpilation.
* **API Error handling**: No matter the endpoint, errors are formatted into the same object format.
* **Permission checked** (optional): Optional behavior to check if the current client has permissions for a resource before performing a request.
This is a stripped-down version of the original library, for Open Cloud.
### Installation
#### Node Installation
Steps to install Node can be found [here](https://nodejs.org).
Run
```
npm install @dynabloxjs/opencloud
```
or
```
yarn add @dynabloxjs/opencloud
```
to install. (**yarn add** requires [yarn](https://yarnpkg.com))
Import it with CommonJS:
```js
const dynablox = require("@dynabloxjs/opencloud");
```
or ESModule:
```js
import * as dynablox from "@dynabloxjs/opencloud";
```
For pre-release builds:
Run
```
npm install dynabloxjs/dynablox_opencloud#node
```
or
```
yarn add dynabloxjs/dynablox_opencloud#node
```
to install the current pre-release build. (**yarn add** requires [yarn](https://yarnpkg.com))
#### Deno Installation
Steps to install Deno can be found [here](https://github.com/denoland/deno_install).
Unlike Node or Python, Deno modules only need to be imported via a path (and then cached).
Once you have done the necessary steps, import it:
```ts
import * as dynablox from "https://deno.land/x/dynablox_opencloud/mod.ts";
```
*NOTE*: You can also specify a version by appending `@{version}` to the module name.
... and it's done! Only the `--allow-net` flag is needed for Dynablox Open Cloud, see [more information about flags in the Deno manual](https://deno.land/manual/getting_started/permissions).
For pre-release builds:
Replace `https://deno.land/x/dynablox_opencloud/mod.ts` with `https://raw.githubusercontent.com/dynabloxjs/dynablox_opencloud/main/mod.ts`, or clone onto your machine and import `mod.ts` from the downloaded folder in your code.
### Starting Guide
*NOTE: If you are not using tooling, you are silly.*
### All Uses (Functional Programming)
In `BaseClient`, there is almost no usage of OOP. All APIs on Open Cloud endpoints can be accessed via `.services`, though with little documentation.
Import `BaseClient` from the module entrypoint, either the module name (NodeJS) or mod.ts (Deno)
Construct a new BaseClient with either API key or other credentials.
```typescript
const client = new BaseClient({
credentials: {
type: "APIKey",
value: "APIKEYHERE"
}
})
```
### Open Cloud (API Key, OOP)
In `OpenCloudClient`, it is mostly object-orientated, with all methods available on `` with clear documentation, though APIs on Open Cloud endpoints are still accessible via `.services`.
Import `OpenCloudClient` from the module entrypoint, either the module name (NodeJS) or mod.ts (Deno)
Construct a new OpenCloudClient with your APIKey.
```typescript
const client = new OpenCloudClient({
credentialsValue: "APIKEYHERE",
})
```
#### Permission Scopes
It is also possible to define **scopes** to tell the client what and what it can not access.
This is similar to the actual Scopes system Roblox uses for OpenCloud and oAuth.
By default, all scopes are allowed.
```typescript
const client = new OpenCloudClient({
credentialsValue: "APIKEYHERE",
scopes: [{
// The scope type, see TSDoc for more options.
scopeType: "universe-datastores.objects",
// Allows for universe ID 13058 and datastoreName.
// a Target part can also be "*" to allow all. Some target parts may be optional.
targetParts: ["13058", "datastoreName"],
// Allows for reading entry values in the DataStore.
operations: ["read"],
// NOTE: this is optional. If set to `true`, `operations` is ignored.
allowAllOperations: false,
}]
})
```
#### Ratelimiting
The OpenCloudClient also has a built-in ratelimit helper. If a ratelimit is reached, it will throw an OpenCloudClientError.
You can opt in for yielding behavior by setting `ratelimiterShouldYield` to `true`:
```typescript
const client = new OpenCloudClient({
credentialsValue: "APIKEYHERE",
ratelimiterShouldYield: true,
})
```
It also exposes the Ratelimiter helper publicly, so you can have mutiple OpenCloudClients using the same ratelimit helper instance:
```typescript
const client1 = new OpenCloudClient({
credentialsValue: "APIKEYHERE",
});
const client2 = new OpenCloudClient({
credentialsValue: "APIKEYHERE",
ratelimiter: client1.ratelimiter,
});
```
### Retries
By default, if a response is `500`, `502`, or `504` it will retry **5** times, each retry having a **250ms** timeout. It is possible to change it:
```typescript
const client = new OpenCloudClient({
credentialsValue: "APIKEYHERE",
// Retry 5 more times on failed requests, if retrying is not wanted, set it to `0`.
requestRetryCount: 5,
// Each retry will take 250ms
requestRetryTimeout: 250
});
```
#### Examples
##### Publishing a Place
Deno
```typescript
import { OpenCloudClient } from "https://deno.land/x/dynablox_opencloud/mod.ts";
const client = new OpenCloudClient({
credentialsValue: "APIKEYHERE",
scopes: [{
// Tell the client we have access to updating place data in the universe 13058, and no other universe.
scopeType: "universe-places",
targetParts: ["13058"],
operations: ["write"],
}],
});
// The methods have "base" because it doesn't actually make any HTTP requests.
const place = client.getBaseUniverse(13058).getBasePlace(1818);
const fileData = await Deno.readFile("./place.rbxl");
// Updates the content of the place for the Saved version type.
const placeVersion = await place.updateContents(fileData, "Saved");
console.log(`Updated place to version ${placeVersion}`);
```
NodeJS
```javascript
const { OpenCloudClient } = require("@dynabloxjs/opencloud");
const fs = require("fs/promises");
const client = new OpenCloudClient({
credentialsValue: "APIKEYHERE",
scopes: [{
// Tell the client we have access to updating place data in the universe 13058, and no other universe.
scopeType: "universe-places",
targetParts: ["13058"],
operations: ["write"],
}],
});
// The methods have "base" because it doesn't actually make any HTTP requests.
const place = client.getBaseUniverse(13058).getBasePlace(1818);
(async () => {
const fileData = await fs.readFile("./place.rbxl");
// Updates the content of the place for the Saved version type.
const placeVersion = await place.updateContents(fileData, "Saved");
console.log(`Updated place to version ${placeVersion}`);
})();
```
##### Accessing DataStores
Deno
```typescript
import { OpenCloudClient } from "https://deno.land/x/dynablox_opencloud/mod.ts";
const client = new OpenCloudClient({
credentialsValue: "APIKEYHERE",
scopes: [{
// Tell the client we have access to reading and listing DataStore objects on universe 13058 and not any other universe.
scopeType: "universe-datastores.objects",
targetParts: ["13058"],
operations: ["read", "list"],
}],
});
// The method has "base" because it doesn't actually make any HTTP requests.
const datastore = client.getBaseUniverse(13058).getStandardDataStore("TestStore");
// `ServicePage` has an async iterator implementation, let's use it.
for await (const keys of datastore.listEntries()) {
keys.forEach(({key}) => {
console.log(key);
if (key.startsWith("Player")) {
const data = await datastore.getEntry(key);
console.log(`${key} data length: ${JSON.stringify(data).length}`);
}
});
}
// Or:
// const keys = await datastore.listEntries().getCurrentPage();
// keys.data.forEach(({key}) => ...);
// Get more data:
// const moreKeys = await keys.getNextPage();
// moreKeys.data.forEach(({key}) => ...);
```
NodeJS
```javascript
const { OpenCloudClient } = require("@dynabloxjs/opencloud");
const client = new OpenCloudClient({
credentialsValue: "APIKEYHERE",
scopes: [{
// Tell the client we have access to reading and listing DataStore objects on universe 13058 and not any other universe.
scopeType: "universe-datastores.objects",
targetParts: ["13058"],
operations: ["read", "list"],
}],
});
// The method has "base" because it doesn't actually make any HTTP requests.
const datastore = client.getBaseUniverse(13058).getStandardDataStore("TestStore");
(async () => {
// `ServicePage` has an async iterator implementation, let's use it.
for await (const keys of datastore.listEntries()) {
keys.forEach(({key}) => {
console.log(key);
if (key.startsWith("Player")) {
const data = await datastore.getEntry(key);
console.log(`${key} data length: ${JSON.stringify(data).length}`);
}
});
}
// Or:
// const keys = await datastore.listEntries().getCurrentPage();
// keys.data.forEach(({key}) => ...);
// Get more data:
// const moreKeys = await keys.getNextPage();
// moreKeys.data.forEach(({key}) => ...);
})();
```
##### Posting a message to be read by MessagingService
Deno
```typescript
import { OpenCloudClient } from "https://deno.land/x/dynablox_opencloud/mod.ts";
const client = new OpenCloudClient({
credentialsValue: "APIKEYHERE",
scopes: [{
// Tell the client we have access to publishing messages on universe 13058 and not any other universe.
scopeType: "universe-messaging-service",
targetParts: ["13058"],
operations: ["publish"],
}],
});
// The method has "base" because it doesn't actually make any HTTP requests.
const universe = client.getBaseUniverse(13058);
// Post the message to the universe.
await universe.postMessage("CoolTopic", { coolData: true });
```
NodeJS
```javascript
const { OpenCloudClient } = require("@dynabloxjs/opencloud");
const client = new OpenCloudClient({
credentialsValue: "APIKEYHERE",
scopes: [{
// Tell the client we have access to publishing messages on universe 13058 and not any other universe.
scopeType: "universe-messaging-service",
targetParts: ["13058"],
operations: ["publish"],
}],
});
// The method has "base" because it doesn't actually make any HTTP requests.
const universe = client.getBaseUniverse(13058);
(async() => {
// Post the message to the universe.
await universe.postMessage("CoolTopic", { coolData: true });
})();
```
## License
[MIT License](https://github.com/dynabloxjs/dynablox_opencloud/blob/main/LICENSE)