tuturuuu 0.0.1
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 +270 -0
- package/package.json +47 -0
- package/src/documents.test.ts +523 -0
- package/src/errors.test.ts +278 -0
- package/src/errors.ts +161 -0
- package/src/index.ts +60 -0
- package/src/storage.test.ts +604 -0
- package/src/storage.ts +702 -0
- package/src/types.test.ts +562 -0
- package/src/types.ts +291 -0
package/README.md
ADDED
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
# tuturuuu
|
|
2
|
+
|
|
3
|
+
Official TypeScript/JavaScript SDK for the Tuturuuu platform.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install tuturuuu
|
|
9
|
+
# or
|
|
10
|
+
yarn add tuturuuu
|
|
11
|
+
# or
|
|
12
|
+
pnpm add tuturuuu
|
|
13
|
+
# or
|
|
14
|
+
bun add tuturuuu
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Quick Start
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
import { TuturuuuClient } from 'tuturuuu';
|
|
21
|
+
|
|
22
|
+
// Initialize the client
|
|
23
|
+
const client = new TuturuuuClient('ttr_your_api_key');
|
|
24
|
+
|
|
25
|
+
// List files
|
|
26
|
+
const files = await client.storage.list({ path: 'documents' });
|
|
27
|
+
|
|
28
|
+
// Upload a file
|
|
29
|
+
const file = new File(['content'], 'example.txt');
|
|
30
|
+
await client.storage.upload(file, { path: 'documents' });
|
|
31
|
+
|
|
32
|
+
// Create a document
|
|
33
|
+
const doc = await client.documents.create({
|
|
34
|
+
name: 'My Document',
|
|
35
|
+
content: { text: 'Hello World' }
|
|
36
|
+
});
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Features
|
|
40
|
+
|
|
41
|
+
- ✅ **Storage Operations** - Upload, download, list, delete files and folders
|
|
42
|
+
- ✅ **Document Management** - Create, read, update, delete workspace documents
|
|
43
|
+
- ✅ **Signed URLs** - Generate temporary shareable links for files
|
|
44
|
+
- ✅ **Storage Analytics** - Track usage, file counts, and limits
|
|
45
|
+
- ✅ **Type-Safe** - Full TypeScript support with type inference
|
|
46
|
+
- ✅ **Error Handling** - Comprehensive error classes for all scenarios
|
|
47
|
+
- ✅ **Validation** - Built-in input validation with Zod schemas
|
|
48
|
+
|
|
49
|
+
## API Reference
|
|
50
|
+
|
|
51
|
+
### Client Initialization
|
|
52
|
+
|
|
53
|
+
```typescript
|
|
54
|
+
import { TuturuuuClient } from 'tuturuuu';
|
|
55
|
+
|
|
56
|
+
// Simple initialization
|
|
57
|
+
const client = new TuturuuuClient('ttr_your_api_key');
|
|
58
|
+
|
|
59
|
+
// With custom configuration
|
|
60
|
+
const client = new TuturuuuClient({
|
|
61
|
+
apiKey: 'ttr_your_api_key',
|
|
62
|
+
baseUrl: 'https://tuturuuu.com/api/v1', // optional
|
|
63
|
+
timeout: 30000 // optional, default 30s
|
|
64
|
+
});
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Storage Operations
|
|
68
|
+
|
|
69
|
+
#### List Files
|
|
70
|
+
|
|
71
|
+
```typescript
|
|
72
|
+
const files = await client.storage.list({
|
|
73
|
+
path: 'documents',
|
|
74
|
+
search: 'report',
|
|
75
|
+
limit: 50,
|
|
76
|
+
offset: 0,
|
|
77
|
+
sortBy: 'created_at',
|
|
78
|
+
sortOrder: 'desc'
|
|
79
|
+
});
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
#### Upload File
|
|
83
|
+
|
|
84
|
+
```typescript
|
|
85
|
+
const file = new File(['content'], 'document.pdf');
|
|
86
|
+
const result = await client.storage.upload(file, {
|
|
87
|
+
path: 'documents',
|
|
88
|
+
upsert: true // overwrite if exists
|
|
89
|
+
});
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
#### Download File
|
|
93
|
+
|
|
94
|
+
```typescript
|
|
95
|
+
const blob = await client.storage.download('documents/report.pdf');
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
#### Delete Files
|
|
99
|
+
|
|
100
|
+
```typescript
|
|
101
|
+
await client.storage.delete([
|
|
102
|
+
'documents/old-report.pdf',
|
|
103
|
+
'images/screenshot.png'
|
|
104
|
+
]);
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
#### Create Folder
|
|
108
|
+
|
|
109
|
+
```typescript
|
|
110
|
+
await client.storage.createFolder('documents', 'reports');
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
#### Share File
|
|
114
|
+
|
|
115
|
+
```typescript
|
|
116
|
+
const { data } = await client.storage.share('documents/report.pdf', {
|
|
117
|
+
expiresIn: 3600 // 1 hour in seconds
|
|
118
|
+
});
|
|
119
|
+
console.log(data.signedUrl);
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
#### Get Analytics
|
|
123
|
+
|
|
124
|
+
```typescript
|
|
125
|
+
const analytics = await client.storage.getAnalytics();
|
|
126
|
+
console.log(`Used: ${analytics.data.totalSize} bytes`);
|
|
127
|
+
console.log(`Files: ${analytics.data.fileCount}`);
|
|
128
|
+
console.log(`Usage: ${analytics.data.usagePercentage}%`);
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### Document Operations
|
|
132
|
+
|
|
133
|
+
#### List Documents
|
|
134
|
+
|
|
135
|
+
```typescript
|
|
136
|
+
const docs = await client.documents.list({
|
|
137
|
+
search: 'meeting',
|
|
138
|
+
limit: 20,
|
|
139
|
+
offset: 0,
|
|
140
|
+
isPublic: false
|
|
141
|
+
});
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
#### Create Document
|
|
145
|
+
|
|
146
|
+
```typescript
|
|
147
|
+
const doc = await client.documents.create({
|
|
148
|
+
name: 'Meeting Notes',
|
|
149
|
+
content: { text: 'Discussion points...' },
|
|
150
|
+
isPublic: false
|
|
151
|
+
});
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
#### Get Document
|
|
155
|
+
|
|
156
|
+
```typescript
|
|
157
|
+
const doc = await client.documents.get('document-id-123');
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
#### Update Document
|
|
161
|
+
|
|
162
|
+
```typescript
|
|
163
|
+
const doc = await client.documents.update('document-id-123', {
|
|
164
|
+
name: 'Updated Meeting Notes',
|
|
165
|
+
content: { text: 'New content...' }
|
|
166
|
+
});
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
#### Delete Document
|
|
170
|
+
|
|
171
|
+
```typescript
|
|
172
|
+
await client.documents.delete('document-id-123');
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
#### Search Documents
|
|
176
|
+
|
|
177
|
+
```typescript
|
|
178
|
+
const results = await client.documents.search('meeting notes');
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## Error Handling
|
|
182
|
+
|
|
183
|
+
The SDK provides specific error classes for different scenarios:
|
|
184
|
+
|
|
185
|
+
```typescript
|
|
186
|
+
import {
|
|
187
|
+
AuthenticationError,
|
|
188
|
+
AuthorizationError,
|
|
189
|
+
NotFoundError,
|
|
190
|
+
ConflictError,
|
|
191
|
+
RateLimitError,
|
|
192
|
+
NetworkError,
|
|
193
|
+
ValidationError
|
|
194
|
+
} from 'tuturuuu';
|
|
195
|
+
|
|
196
|
+
try {
|
|
197
|
+
await client.storage.upload(file);
|
|
198
|
+
} catch (error) {
|
|
199
|
+
if (error instanceof AuthenticationError) {
|
|
200
|
+
// Invalid API key
|
|
201
|
+
} else if (error instanceof AuthorizationError) {
|
|
202
|
+
// Insufficient permissions
|
|
203
|
+
} else if (error instanceof NotFoundError) {
|
|
204
|
+
// Resource not found
|
|
205
|
+
} else if (error instanceof ConflictError) {
|
|
206
|
+
// Resource already exists
|
|
207
|
+
} else if (error instanceof RateLimitError) {
|
|
208
|
+
// Rate limit exceeded
|
|
209
|
+
} else if (error instanceof NetworkError) {
|
|
210
|
+
// Network or timeout error
|
|
211
|
+
} else if (error instanceof ValidationError) {
|
|
212
|
+
// Invalid input
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
## TypeScript Support
|
|
218
|
+
|
|
219
|
+
The SDK is written in TypeScript and provides full type definitions:
|
|
220
|
+
|
|
221
|
+
```typescript
|
|
222
|
+
import type {
|
|
223
|
+
StorageObject,
|
|
224
|
+
Document,
|
|
225
|
+
ListStorageOptions,
|
|
226
|
+
UploadOptions,
|
|
227
|
+
ShareOptions,
|
|
228
|
+
CreateDocumentData
|
|
229
|
+
} from 'tuturuuu';
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
## Examples
|
|
233
|
+
|
|
234
|
+
See the [examples](./examples) directory for complete usage examples:
|
|
235
|
+
|
|
236
|
+
- [basic-usage.ts](./examples/basic-usage.ts) - Basic operations
|
|
237
|
+
- [error-handling.ts](./examples/error-handling.ts) - Error handling patterns
|
|
238
|
+
|
|
239
|
+
## API Key Management
|
|
240
|
+
|
|
241
|
+
To use this SDK, you need a Tuturuuu API key:
|
|
242
|
+
|
|
243
|
+
1. Log in to your Tuturuuu workspace
|
|
244
|
+
2. Navigate to Settings → API Keys
|
|
245
|
+
3. Click "Create API Key"
|
|
246
|
+
4. Set a descriptive name
|
|
247
|
+
5. Assign a Workspace Role (determines permissions)
|
|
248
|
+
6. Optionally set an expiration date
|
|
249
|
+
7. Copy the generated key (starts with `ttr_`)
|
|
250
|
+
|
|
251
|
+
**Important:** Keep your API key secure and never commit it to version control.
|
|
252
|
+
|
|
253
|
+
### Permissions
|
|
254
|
+
|
|
255
|
+
API keys inherit permissions from their assigned **Workspace Role**:
|
|
256
|
+
|
|
257
|
+
- **Storage Operations** (list, upload, download, delete, folders, share, analytics) require `manage_drive` permission
|
|
258
|
+
- **Document Operations** (list, create, get, update, delete, search) require `manage_documents` permission
|
|
259
|
+
|
|
260
|
+
To modify what an API key can do, update its assigned role's permissions in Settings → Roles.
|
|
261
|
+
|
|
262
|
+
## License
|
|
263
|
+
|
|
264
|
+
MIT
|
|
265
|
+
|
|
266
|
+
## Support
|
|
267
|
+
|
|
268
|
+
- Documentation: <https://docs.tuturuuu.com>
|
|
269
|
+
- Issues: <https://github.com/tutur3u/platform/issues>
|
|
270
|
+
- Discord: <https://discord.gg/tuturuuu>
|
package/package.json
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "tuturuuu",
|
|
3
|
+
"version": "0.0.1",
|
|
4
|
+
"description": "Official TypeScript/JavaScript SDK for the Tuturuuu platform",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "Tuturuuu",
|
|
7
|
+
"homepage": "https://tuturuuu.com",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "https://github.com/tutur3u/platform",
|
|
11
|
+
"directory": "packages/sdk"
|
|
12
|
+
},
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/tutur3u/platform/issues"
|
|
15
|
+
},
|
|
16
|
+
"keywords": ["tuturuuu", "sdk", "api"],
|
|
17
|
+
"main": "./src/index.ts",
|
|
18
|
+
"types": "./src/index.ts",
|
|
19
|
+
"exports": {
|
|
20
|
+
".": "./src/index.ts",
|
|
21
|
+
"./storage": "./src/storage.ts",
|
|
22
|
+
"./types": "./src/types.ts",
|
|
23
|
+
"./errors": "./src/errors.ts"
|
|
24
|
+
},
|
|
25
|
+
"files": ["src", "README.md", "LICENSE"],
|
|
26
|
+
"publishConfig": {
|
|
27
|
+
"access": "public"
|
|
28
|
+
},
|
|
29
|
+
"scripts": {
|
|
30
|
+
"test": "vitest run",
|
|
31
|
+
"test:watch": "vitest"
|
|
32
|
+
},
|
|
33
|
+
"dependencies": {
|
|
34
|
+
"@tuturuuu/supabase": "0.1.1",
|
|
35
|
+
"zod": "^4.1.12"
|
|
36
|
+
},
|
|
37
|
+
"devDependencies": {
|
|
38
|
+
"@tuturuuu/typescript-config": "0.1.0",
|
|
39
|
+
"@types/node": "^24.9.1",
|
|
40
|
+
"typescript": "^5.9.3",
|
|
41
|
+
"vitest": "^3.2.4"
|
|
42
|
+
},
|
|
43
|
+
"engines": {
|
|
44
|
+
"node": ">=18.0.0"
|
|
45
|
+
},
|
|
46
|
+
"packageManager": "bun@1.3.0"
|
|
47
|
+
}
|