forge-server-utils
Version:
Tools for accessing Autodesk Forge APIs from Node.js apps and from browser.
149 lines (119 loc) • 6 kB
Markdown
# forge-server-utils
[](https://badge.fury.io/js/forge-server-utils)
[](http://opensource.org/licenses/MIT)
Unofficial tools for accessing [Autodesk Forge](https://developer.autodesk.com/) APIs from Node.js applications
and from browsers, built using [TypeScript](https://www.typescriptlang.org) and modern language features like
[async/await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function)
or [generators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*).
## Usage
### Server Side
The TypeScript implementation is transpiled into CommonJS JavaScript module with type definition files,
so you can use it both in Node.js projects, and in TypeScript projects:
```js
// JavaScript
const { DataManagementClient } = require('forge-server-utils');
```
```ts
// TypeScript
import {
DataManagementClient,
IBucket,
IObject,
IResumableUploadRange,
DataRetentionPolicy
} from 'forge-server-utils';
```
#### Authentication
If you need to generate [2-legged tokens](https://forge.autodesk.com/en/docs/oauth/v2/tutorials/get-2-legged-token)
manually, you can use the `AuthenticationClient` class:
```js
const { AuthenticationClient } = require('forge-server-utils');
const { FORGE_CLIENT_ID, FORGE_CLIENT_SECRET } = process.env;
const auth = new AuthenticationClient(FORGE_CLIENT_ID, FORGE_CLIENT_SECRET);
const authentication = await auth.authenticate(['bucket:read', 'data:read']);
console.log('2-legged token', authentication.access_token);
```
Other API clients in this library are typically configured using a simple JavaScript object
containing either `client_id` and `client_secret` properties (for 2-legged authentication),
or a single `token` property (for authentication using a pre-generated access token):
```js
const { DataManagementClient, BIM360Client } = require('forge-server-utils');
const dm = new DataManagementClient({ client_id: '...', client_secret: '...' });
const bim360 = new BIM360Client({ token: '...' });
```
#### Data Management
```js
const { DataManagementClient } = require('forge-server-utils');
const { FORGE_CLIENT_ID, FORGE_CLIENT_SECRET } = process.env;
const data = new DataManagementClient({ client_id: FORGE_CLIENT_ID, client_secret: FORGE_CLIENT_SECRET });
const buckets = await data.listBuckets();
console.log('Buckets', buckets.map(bucket => bucket.bucketKey).join(','));
const objects = await data.listObjects('foo-bucket');
console.log('Objects', objects.map(object => object.objectId).join(','));
```
#### Model Derivatives
```js
const { ModelDerivativeClient } = require('forge-server-utils');
const { FORGE_CLIENT_ID, FORGE_CLIENT_SECRET } = process.env;
const derivatives = new ModelDerivativeClient({ client_id: FORGE_CLIENT_ID, client_secret: FORGE_CLIENT_SECRET });
const job = await derivatives.submitJob('<your-document-urn>', [{ type: 'svf', views: ['2d', '3d'] }]);
console.log('Job', job);
```
#### Design Automation
```js
const { DesignAutomationClient } = require('forge-server-utils');
const { FORGE_CLIENT_ID, FORGE_CLIENT_SECRET } = process.env;
const client = new DesignAutomationClient({ client_id: FORGE_CLIENT_ID, client_secret: FORGE_CLIENT_SECRET });
const bundles = await client.listAppBundles();
console.log('App bundles', bundles);
```
#### Reality Capture
```js
const { OutputFormat, RealityCaptureClient, SceneType } = require('forge-server-utils');
const { FORGE_CLIENT_ID, FORGE_CLIENT_SECRET } = process.env;
const recap = new RealityCaptureClient({ client_id: FORGE_CLIENT_ID, client_secret: FORGE_CLIENT_SECRET });
const options = {
scenename: '<scene name>',
scenetype: SceneType.Aerial,
format: OutputFormat.RecapPhotoMesh,
callback: '<callback>'
};
const photoscene = await recap.createPhotoScene(options);
console.log('Photoscene', photoscene);
```
### Client Side (experimental)
The transpiled output from TypeScript is also bundled using [webpack](https://webpack.js.org),
so you can use the same functionality in a browser. There is a caveat, unfortunately: at the moment
it is not possible to request Forge access tokens from the browser
due to [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) limitations,
so when creating instances of the various clients, instead of providing client ID and secret
you will have to provide the token directly.
```html
<script src="https://cdn.jsdelivr.net/npm/forge-server-utils/dist/browser/forge-server-utils.js"></script>
<script>
const data = new forge.DataManagementClient({ token: '<your access token>' });
const deriv = new forge.ModelDerivativeClient({ token: '<your access token>' });
data.listBuckets()
.then(buckets => { console.log('Buckets', buckets); })
.catch(err => { console.error('Could not list buckets', err); });
deriv.submitJob('<your document urn>', [{ type: 'svf', views: ['2d', '3d'] }])
.then(job => { console.log('Translation job', job); })
.catch(err => { console.error('Could not start translation', err); });
</script>
```
Note that you can also request a specific version of the library from CDN by appending `@<version>`
to the npm package name, for example, `https://cdn.jsdelivr.net/npm/forge-server-utils@4.0.0/dist/browser/forge-server-utils.js`.
## Testing
```bash
export FORGE_CLIENT_ID=<your-client-id>
export FORGE_CLIENT_SECRET=<your-client-secret>
export FORGE_BUCKET=<your-test-bucket>
export FORGE_MODEL_URN=<testing-model-urn>
yarn run build # Transpile TypeScript into JavaScript
yarn test
```