@workast/sdk 2.3.0 → 3.0.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 +88 -59
- package/dist/index.cjs +1875 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +13361 -0
- package/dist/index.d.ts +13361 -0
- package/dist/index.js +1843 -0
- package/dist/index.js.map +1 -0
- package/package.json +34 -52
- package/CHANGELOG.md +0 -59
- package/dist/workast.min.js +0 -1
- package/index.d.ts +0 -163
- package/lib/workast.js +0 -1850
package/README.md
CHANGED
|
@@ -1,83 +1,112 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @workast/sdk
|
|
2
2
|
|
|
3
|
-
[](https://coveralls.io/github/workast/workast-sdk-js?branch=master)
|
|
6
|
-
[](https://snyk.io/test/github/workast/workast-sdk-js?targetFile=package.json)
|
|
7
|
-
[](https://david-dm.org/workast/workast-sdk-js)
|
|
8
|
-
[](https://david-dm.org/workast/workast-sdk-js?type=dev)
|
|
3
|
+
[](https://www.npmjs.com/package/@workast/sdk)
|
|
4
|
+
[](https://github.com/workast/sdk/actions/workflows/ci.yml)
|
|
9
5
|
|
|
10
|
-
|
|
6
|
+
TypeScript library for the [Workast API](https://developers.workast.com/). Works in Node.js 18+ and in browsers.
|
|
11
7
|
|
|
12
|
-
|
|
8
|
+
## Installation
|
|
13
9
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
- [Usage](#usage)
|
|
18
|
-
- [Releases](CHANGELOG.md)
|
|
19
|
-
- [Responsible disclosure](#responsible-disclosure)
|
|
10
|
+
```sh
|
|
11
|
+
npm install @workast/sdk
|
|
12
|
+
```
|
|
20
13
|
|
|
21
|
-
##
|
|
22
|
-
We use [browserslist](https://github.com/browserslist/browserslist) to handle our supported versions for both node and browsers. [You can see the updated list here.](https://browserl.ist/?q=%3E+1%25%2C+last+2+versions%2C+not+dead%2C+maintained+node+versions)
|
|
14
|
+
## Usage
|
|
23
15
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
```
|
|
27
|
-
|
|
16
|
+
Create a token in Workast under **Preferences → API**. Secret API keys are server-only — passing `apiKey` in a browser throws.
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import { Workast } from '@workast/sdk';
|
|
20
|
+
|
|
21
|
+
const workast = new Workast({ apiKey: process.env.WORKAST_API_KEY });
|
|
22
|
+
// shorthand: new Workast(process.env.WORKAST_API_KEY)
|
|
23
|
+
|
|
24
|
+
const task = await workast.tasks.create(listId, { text: 'Ship SDK' });
|
|
25
|
+
await workast.tasks.complete(task.id);
|
|
26
|
+
const page = await workast.tasks.list({
|
|
27
|
+
predicates: [{ type: 'status', attribute: 'status', comparison: 'eq', value: 'pending' }],
|
|
28
|
+
});
|
|
28
29
|
```
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
30
|
+
|
|
31
|
+
Browser / user session:
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
const workast = new Workast({ token: sessionToken });
|
|
35
|
+
// or
|
|
36
|
+
const workast = new Workast({ getToken: () => auth.getAccessToken() });
|
|
32
37
|
```
|
|
33
38
|
|
|
34
|
-
|
|
39
|
+
### Configuration
|
|
35
40
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
41
|
+
| Option | Description |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| `apiKey` | Secret API token. Server-only. |
|
|
44
|
+
| `token` | User or session token. Allowed in browsers. |
|
|
45
|
+
| `getToken` | Function that returns a token (sync or async). |
|
|
46
|
+
| `baseUrl` | API host. Defaults to `https://api.workast.com`. |
|
|
47
|
+
| `headers` | Extra headers (for example `W-USER-ID`, `W-TEAM-ID`). `Authorization` is set by the client. |
|
|
48
|
+
| `fetch` | Custom `fetch` implementation. |
|
|
39
49
|
|
|
40
|
-
|
|
50
|
+
`withHeaders(h)` returns a cloned client. `setHeaders(h)` updates the current one.
|
|
41
51
|
|
|
42
|
-
|
|
52
|
+
```ts
|
|
53
|
+
const workast = new Workast({
|
|
54
|
+
apiKey: process.env.WORKAST_API_KEY,
|
|
55
|
+
headers: { 'W-USER-ID': userId },
|
|
56
|
+
});
|
|
43
57
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
console.log('Task data: %O', task);
|
|
47
|
-
} catch (err) {
|
|
48
|
-
console.error('Something went wrong: %O', err);
|
|
49
|
-
}
|
|
58
|
+
await workast.withHeaders({ 'W-USER-ID': otherUserId }).tasks.create(listId, { text: 'Hi' });
|
|
59
|
+
workast.setHeaders({ 'W-TEAM-ID': teamId });
|
|
50
60
|
```
|
|
51
61
|
|
|
52
|
-
###
|
|
53
|
-
```javascript
|
|
54
|
-
import Workast from '@workast/sdk';
|
|
62
|
+
### Errors
|
|
55
63
|
|
|
56
|
-
|
|
64
|
+
Failed requests throw a subclass of `ApiError`:
|
|
65
|
+
|
|
66
|
+
| Status | Error |
|
|
67
|
+
| --- | --- |
|
|
68
|
+
| 400 | `ValidationError` |
|
|
69
|
+
| 401 | `AuthenticationError` |
|
|
70
|
+
| 403 | `PermissionError` |
|
|
71
|
+
| 404 | `NotFoundError` |
|
|
72
|
+
| other | `ApiError` |
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
import { NotFoundError } from '@workast/sdk';
|
|
57
76
|
|
|
58
77
|
try {
|
|
59
|
-
|
|
60
|
-
console.log('Task data: %O', task);
|
|
78
|
+
await workast.tasks.retrieve(taskId);
|
|
61
79
|
} catch (err) {
|
|
62
|
-
|
|
80
|
+
if (err instanceof NotFoundError) {
|
|
81
|
+
console.log(err.status, err.body);
|
|
82
|
+
}
|
|
63
83
|
}
|
|
64
84
|
```
|
|
65
85
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
86
|
+
## Resources
|
|
87
|
+
|
|
88
|
+
`tasks` · `lists` · `fields` · `users` · `searches` · `tags` · `notes` · `notifications` · `meetings` · `calendar.events` · `workflows` · `reactions` · `attachments` · `tokens`
|
|
89
|
+
|
|
90
|
+
Methods use `create` / `retrieve` / `update` / `list` / `del`, plus domain verbs like `complete` and `assign`. Path ids first, body second, request options last. Types match the [API reference](https://developers.workast.com/).
|
|
91
|
+
|
|
92
|
+
## Upgrading from v2
|
|
93
|
+
|
|
94
|
+
v3 is a rewrite. The v2 positional constructor, `apiCall`, and generated resource helpers are gone. A string argument is now a secret `apiKey` (server-only), not a session token.
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
// v2
|
|
98
|
+
const workast = new Workast(process.env.WORKAST_TOKEN);
|
|
99
|
+
|
|
100
|
+
// v3
|
|
101
|
+
const workast = new Workast({ apiKey: process.env.WORKAST_API_KEY });
|
|
80
102
|
```
|
|
81
103
|
|
|
82
|
-
|
|
83
|
-
|
|
104
|
+
What shipped in each version is on [Releases](https://github.com/workast/sdk/releases).
|
|
105
|
+
|
|
106
|
+
## Contributing
|
|
107
|
+
|
|
108
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md). To report a vulnerability, see [SECURITY.md](SECURITY.md).
|
|
109
|
+
|
|
110
|
+
## License
|
|
111
|
+
|
|
112
|
+
MIT
|