mtlx-sdk 0.10.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +20 -161
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,175 +1,34 @@
|
|
|
1
|
-
[](https://codecov.io/gh/bhouston/mtlx)
|
|
2
|
-
|
|
3
1
|
# mtlx-sdk
|
|
4
2
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
## Installation
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
npm install mtlx-sdk
|
|
11
|
-
# or
|
|
12
|
-
pnpm add mtlx-sdk
|
|
13
|
-
# or
|
|
14
|
-
yarn add mtlx-sdk
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
## Quick Start
|
|
18
|
-
|
|
19
|
-
The SDK uses a **functional approach** - all API operations are exported as standalone functions that take a client instance as their first parameter. Every material belongs directly to a user (there are no organizations or projects).
|
|
20
|
-
|
|
21
|
-
```typescript
|
|
22
|
-
import { createSecretTokenInstance, listAssets, getAsset } from 'mtlx-sdk';
|
|
23
|
-
|
|
24
|
-
const userName = 'alice';
|
|
25
|
-
|
|
26
|
-
// Create a client instance (host defaults to https://api.mtlx.ai)
|
|
27
|
-
const client = createSecretTokenInstance({
|
|
28
|
-
secretToken: 'your-api-token',
|
|
29
|
-
});
|
|
30
|
-
|
|
31
|
-
// List a user's materials
|
|
32
|
-
const assets = await listAssets(client, {
|
|
33
|
-
query: { userName },
|
|
34
|
-
});
|
|
3
|
+
<img src="https://raw.githubusercontent.com/bhouston/mtlx/main/assets/logo.webp" alt="mtlx logo" width="96">
|
|
35
4
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
## Features
|
|
43
|
-
|
|
44
|
-
- **Functional API design** - All operations are exported as standalone functions
|
|
45
|
-
- Full TypeScript support with complete type definitions
|
|
46
|
-
- Zod schema validation for requests and responses
|
|
47
|
-
- Axios-based HTTP client with automatic error handling
|
|
48
|
-
- Support for all MTLX.ai API endpoints:
|
|
49
|
-
- Materials (MaterialX assets, always stored as `.mtlx.zip`)
|
|
50
|
-
- Users and authentication
|
|
51
|
-
- Comments and notifications
|
|
52
|
-
- File uploads and downloads
|
|
53
|
-
- API tokens
|
|
54
|
-
|
|
55
|
-
## Uploading a Material
|
|
56
|
-
|
|
57
|
-
The SDK provides a simple helper function for uploading files. Here's a complete example:
|
|
58
|
-
|
|
59
|
-
```typescript
|
|
60
|
-
import { readFile } from 'node:fs/promises';
|
|
61
|
-
import { basename } from 'node:path';
|
|
62
|
-
import { createSecretTokenInstance, uploadFile, createAsset } from 'mtlx-sdk';
|
|
63
|
-
|
|
64
|
-
const userName = 'alice';
|
|
65
|
-
|
|
66
|
-
const client = createSecretTokenInstance({
|
|
67
|
-
secretToken: 'your-api-token',
|
|
68
|
-
});
|
|
69
|
-
|
|
70
|
-
// Read the file and extract filename (loose `.mtlx` or packaged `.mtlx.zip`)
|
|
71
|
-
const fileData = await readFile('copper.mtlx.zip');
|
|
72
|
-
const filename = basename('copper.mtlx.zip');
|
|
73
|
-
|
|
74
|
-
// Upload the file (infers MIME type and uploads)
|
|
75
|
-
const uploadToken = await uploadFile(client, {
|
|
76
|
-
params: { userName },
|
|
77
|
-
fileData,
|
|
78
|
-
filename,
|
|
79
|
-
});
|
|
80
|
-
|
|
81
|
-
// Create the asset record with the upload token. The API validates the
|
|
82
|
-
// MaterialX document during ingest and rejects malformed content with 400.
|
|
83
|
-
const asset = await createAsset(client, {
|
|
84
|
-
params: { userName },
|
|
85
|
-
body: {
|
|
86
|
-
name: 'copper',
|
|
87
|
-
description: 'A brushed copper material',
|
|
88
|
-
type: 'MATERIAL',
|
|
89
|
-
uploadToken,
|
|
90
|
-
visibility: 'PUBLIC',
|
|
91
|
-
shareLicense: 'CC_BY',
|
|
92
|
-
},
|
|
93
|
-
});
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
The `uploadFile` helper:
|
|
97
|
-
|
|
98
|
-
- Accepts file data (Buffer or Uint8Array) and filename
|
|
99
|
-
- Infers the MIME type from the file extension
|
|
100
|
-
- Prepares the upload and gets a signed URL
|
|
101
|
-
- Uploads the file to the signed URL
|
|
102
|
-
- Returns the upload token for use in `createAsset`
|
|
103
|
-
|
|
104
|
-
**Note:** In Node.js environments, you'll need to read the file yourself using `readFile` from `node:fs/promises` before calling `uploadFile`. In browser environments, you can pass a `File` object directly to `uploadFileToUploadUrl()` or convert it to an `ArrayBuffer`/`Uint8Array` for `uploadFile`.
|
|
105
|
-
|
|
106
|
-
For more control, you can use `prepareAssetUpload()` and `uploadFileToUploadUrl()` directly.
|
|
107
|
-
|
|
108
|
-
## API Reference
|
|
109
|
-
|
|
110
|
-
### Client Configuration
|
|
111
|
-
|
|
112
|
-
The SDK provides several client creation functions depending on your authentication method:
|
|
5
|
+
[](https://www.npmjs.com/package/mtlx-sdk)
|
|
6
|
+
[](https://mtlx.ben3d.ca/docs/sdk/)
|
|
7
|
+
[](https://github.com/bhouston/mtlx/actions/workflows/ci.yml)
|
|
8
|
+
[](https://www.npmjs.com/package/mtlx-sdk)
|
|
9
|
+
[](https://codecov.io/gh/bhouston/mtlx)
|
|
10
|
+
[](https://discord.gg/wzQWaBBxup)
|
|
113
11
|
|
|
114
|
-
|
|
115
|
-
import {
|
|
116
|
-
createSecretTokenInstance, // For API tokens (most common)
|
|
117
|
-
createFrontendTokenInstance, // For frontend tokens
|
|
118
|
-
createSessionInstance, // For user sessions
|
|
119
|
-
createAnonymousClient, // For anonymous access
|
|
120
|
-
} from 'mtlx-sdk';
|
|
12
|
+
Typed JavaScript and TypeScript client for the [MTLX.ai](https://mtlx.ai) REST API. Search hosted materials, upload packages, and work with users, comments, and notifications through standalone functions.
|
|
121
13
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
const client = createSecretTokenInstance({
|
|
125
|
-
secretToken: 'your-api-token',
|
|
126
|
-
// host: 'https://api.mtlx.ai', // Optional, defaults to production API
|
|
127
|
-
});
|
|
14
|
+
```sh
|
|
15
|
+
npm install mtlx-sdk
|
|
128
16
|
```
|
|
129
17
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
### Available Functions
|
|
133
|
-
|
|
134
|
-
The SDK exports functions for all API operations. Here are the main categories:
|
|
135
|
-
|
|
136
|
-
**Assets (materials):**
|
|
18
|
+
```ts
|
|
19
|
+
import { createSecretTokenInstance, listAssets } from 'mtlx-sdk';
|
|
137
20
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
- `updateAsset()` - Update material metadata or replace its file
|
|
142
|
-
- `deleteAsset()` - Delete a material
|
|
143
|
-
- `uploadFile()` - Upload a file and get upload token (helper function)
|
|
144
|
-
- `prepareAssetUpload()` - Get signed upload URL and token
|
|
145
|
-
- `uploadFileToUploadUrl()` - Upload file to signed URL
|
|
146
|
-
|
|
147
|
-
**Other resources:**
|
|
148
|
-
|
|
149
|
-
- Users and authentication
|
|
150
|
-
- Comments and notifications
|
|
151
|
-
- API tokens
|
|
152
|
-
|
|
153
|
-
All functions follow the pattern: `functionName(client, props)` where `client` is the API client instance and `props` contains the request parameters.
|
|
154
|
-
|
|
155
|
-
## Zod Schemas
|
|
156
|
-
|
|
157
|
-
The SDK exports Zod schemas for all API request and response types, enabling runtime validation:
|
|
158
|
-
|
|
159
|
-
```typescript
|
|
160
|
-
import { assetSchema, createAssetBodySchema } from 'mtlx-sdk';
|
|
161
|
-
|
|
162
|
-
// Validate an asset object
|
|
163
|
-
const validatedAsset = assetSchema.parse(assetData);
|
|
164
|
-
|
|
165
|
-
// Validate create asset input
|
|
166
|
-
const validatedInput = createAssetBodySchema.parse(createAssetInput);
|
|
21
|
+
const client = createSecretTokenInstance({ secretToken: process.env.MTLX_API_TOKEN! });
|
|
22
|
+
const assets = await listAssets(client, { query: { userName: 'alice' } });
|
|
23
|
+
console.log(assets);
|
|
167
24
|
```
|
|
168
25
|
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
- Node.js >= 23.0.0
|
|
26
|
+
Keep secret tokens on the server. See the [SDK guide](https://mtlx.ben3d.ca/docs/sdk/) for authentication, uploads, schemas, and the [API reference](https://mtlx.ben3d.ca/docs/api/sdk/).
|
|
172
27
|
|
|
173
28
|
## License
|
|
174
29
|
|
|
175
30
|
MIT
|
|
31
|
+
|
|
32
|
+
## Author
|
|
33
|
+
|
|
34
|
+
[Ben Houston](https://ben3d.ca), Sponsored by [Land of Assets](https://landofassets.com).
|