Skip to content

Commit cdc7a25

Browse files
hotlonghotlong
authored
Merge pull request #595 from objectstack-ai/copilot/update-official-documentation
2 parents 5b6fc1c + c0f8230 commit cdc7a25

9 files changed

Lines changed: 138 additions & 124 deletions

File tree

‎content/docs/references/api/auth-endpoints.mdx‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: Auth Endpoints
3+
description: Auth Endpoints protocol schemas
4+
---
5+
6+
Authentication Endpoint Specification
7+
8+
Defines the canonical HTTP endpoints for the authentication service.
9+
10+
Based on better-auth v1.4.18 endpoint conventions.
11+
12+
NOTE: ObjectStack's auth implementation uses better-auth library which has
13+
14+
established endpoint conventions. This spec documents those conventions as
15+
16+
the canonical API contract.
17+
18+
<Callout type="info">
19+
**Source:** `packages/spec/src/api/auth-endpoints.zod.ts`
20+
</Callout>
21+
22+
## TypeScript Usage
23+
24+
```typescript
25+
import { AuthEndpoint } from '@objectstack/spec/api';
26+
import type { AuthEndpoint } from '@objectstack/spec/api';
27+
28+
// Validate data
29+
const result = AuthEndpoint.parse(data);
30+
```
31+
32+
---
33+
34+
## AuthEndpoint
35+
36+
### Properties
37+
38+
| Property | Type | Required | Description |
39+
| :--- | :--- | :--- | :--- |
40+
| **signInEmail** | `Object` | ✅ | |
41+
| **signUpEmail** | `Object` | ✅ | |
42+
| **signOut** | `Object` | ✅ | |
43+
| **getSession** | `Object` | ✅ | |
44+
| **forgetPassword** | `Object` | ✅ | |
45+
| **resetPassword** | `Object` | ✅ | |
46+
| **sendVerificationEmail** | `Object` | ✅ | |
47+
| **verifyEmail** | `Object` | ✅ | |
48+
49+
50+
---
51+

‎content/docs/references/api/auth.mdx‎

Lines changed: 3 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -1,136 +1,18 @@
11
---
22
title: Auth
3-
description: Auth protocol schemas and endpoints
3+
description: Auth protocol schemas
44
---
55

66
Authentication Service Protocol
77

88
Defines the standard API contracts for Identity, Session Management,
9+
910
and Access Control.
1011

1112
<Callout type="info">
12-
**Source:** `packages/spec/src/api/auth.zod.ts`, `packages/spec/src/api/auth-endpoints.zod.ts`
13+
**Source:** `packages/spec/src/api/auth.zod.ts`
1314
</Callout>
1415

15-
## Endpoints
16-
17-
The authentication service uses [better-auth](https://www.better-auth.com/) endpoints as the canonical API contract.
18-
All endpoints are relative to the auth base path (default: `/api/v1/auth`).
19-
20-
### Email/Password Authentication
21-
22-
| Endpoint | Method | Path | Description |
23-
| :--- | :--- | :--- | :--- |
24-
| **Sign In** | `POST` | `/sign-in/email` | Sign in with email and password |
25-
| **Sign Up** | `POST` | `/sign-up/email` | Register new user with email and password |
26-
| **Sign Out** | `POST` | `/sign-out` | Sign out current user |
27-
28-
### Session Management
29-
30-
| Endpoint | Method | Path | Description |
31-
| :--- | :--- | :--- | :--- |
32-
| **Get Session** | `GET` | `/get-session` | Get current user session |
33-
34-
### Password Management
35-
36-
| Endpoint | Method | Path | Description |
37-
| :--- | :--- | :--- | :--- |
38-
| **Forget Password** | `POST` | `/forget-password` | Request password reset email |
39-
| **Reset Password** | `POST` | `/reset-password` | Reset password with token |
40-
41-
### Email Verification
42-
43-
| Endpoint | Method | Path | Description |
44-
| :--- | :--- | :--- | :--- |
45-
| **Send Verification** | `POST` | `/send-verification-email` | Send email verification link |
46-
| **Verify Email** | `GET` | `/verify-email` | Verify email with token |
47-
48-
### OAuth (when providers configured)
49-
50-
| Endpoint | Method | Path | Description |
51-
| :--- | :--- | :--- | :--- |
52-
| **Authorize** | `GET` | `/authorize/:provider` | Start OAuth flow |
53-
| **Callback** | `GET` | `/callback/:provider` | OAuth callback |
54-
55-
### 2FA (when enabled)
56-
57-
| Endpoint | Method | Path | Description |
58-
| :--- | :--- | :--- | :--- |
59-
| **Enable 2FA** | `POST` | `/two-factor/enable` | Enable two-factor authentication |
60-
| **Verify 2FA** | `POST` | `/two-factor/verify` | Verify 2FA code |
61-
62-
### Passkeys (when enabled)
63-
64-
| Endpoint | Method | Path | Description |
65-
| :--- | :--- | :--- | :--- |
66-
| **Register Passkey** | `POST` | `/passkey/register` | Register a passkey |
67-
| **Authenticate** | `POST` | `/passkey/authenticate` | Authenticate with passkey |
68-
69-
### Magic Links (when enabled)
70-
71-
| Endpoint | Method | Path | Description |
72-
| :--- | :--- | :--- | :--- |
73-
| **Send Magic Link** | `POST` | `/magic-link/send` | Send magic link email |
74-
| **Verify Magic Link** | `GET` | `/magic-link/verify` | Verify magic link |
75-
76-
## Usage Examples
77-
78-
### Using the ObjectStack Client
79-
80-
```typescript
81-
import { ObjectStackClient } from '@objectstack/client';
82-
83-
const client = new ObjectStackClient({
84-
baseUrl: 'http://localhost:3000'
85-
});
86-
87-
// Register
88-
await client.auth.register({
89-
email: 'user@example.com',
90-
password: 'SecurePassword123!',
91-
name: 'John Doe'
92-
});
93-
94-
// Login
95-
await client.auth.login({
96-
type: 'email',
97-
email: 'user@example.com',
98-
password: 'SecurePassword123!'
99-
});
100-
101-
// Get session
102-
const session = await client.auth.me();
103-
104-
// Logout
105-
await client.auth.logout();
106-
```
107-
108-
### Using Direct API Calls
109-
110-
```bash
111-
# Register
112-
curl -X POST http://localhost:3000/api/v1/auth/sign-up/email \
113-
-H "Content-Type: application/json" \
114-
-d '{"email":"user@example.com","password":"SecurePassword123!","name":"John Doe"}'
115-
116-
# Login
117-
curl -X POST http://localhost:3000/api/v1/auth/sign-in/email \
118-
-H "Content-Type: application/json" \
119-
-d '{"email":"user@example.com","password":"SecurePassword123!"}'
120-
121-
# Get session
122-
curl http://localhost:3000/api/v1/auth/get-session \
123-
-H "Authorization: Bearer YOUR_TOKEN"
124-
125-
# Logout
126-
curl -X POST http://localhost:3000/api/v1/auth/sign-out \
127-
-H "Authorization: Bearer YOUR_TOKEN"
128-
```
129-
130-
---
131-
132-
## Request/Response Schemas
133-
13416
## TypeScript Usage
13517

13618
```typescript

‎content/docs/references/api/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ This section contains all protocol schemas for the api layer of ObjectStack.
88
<Cards>
99
<Card href="/docs/references/api/analytics" title="Analytics" description="Source: packages/spec/src/api/analytics.zod.ts" />
1010
<Card href="/docs/references/api/auth" title="Auth" description="Source: packages/spec/src/api/auth.zod.ts" />
11+
<Card href="/docs/references/api/auth-endpoints" title="Auth Endpoints" description="Source: packages/spec/src/api/auth-endpoints.zod.ts" />
1112
<Card href="/docs/references/api/batch" title="Batch" description="Source: packages/spec/src/api/batch.zod.ts" />
1213
<Card href="/docs/references/api/contract" title="Contract" description="Source: packages/spec/src/api/contract.zod.ts" />
1314
<Card href="/docs/references/api/discovery" title="Discovery" description="Source: packages/spec/src/api/discovery.zod.ts" />

‎content/docs/references/api/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
"pages": [
44
"analytics",
55
"auth",
6+
"auth-endpoints",
67
"batch",
78
"connector",
89
"contract",

‎content/docs/references/api/protocol.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -428,6 +428,7 @@ const result = AiChatRequest.parse(data);
428428
| **apiName** | `string` | ✅ | API name |
429429
| **capabilities** | `Object` | optional | Supported features/capabilities |
430430
| **endpoints** | `Object` | optional | Available endpoint paths |
431+
| **services** | `Record<string, Object>` | optional | Per-service availability map |
431432

432433

433434
---

‎content/docs/references/data/data-engine.mdx‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,24 @@ The Data Engine acts as the "Driver" layer in the Hexagonal Architecture.
2222
## TypeScript Usage
2323

2424
```typescript
25-
import { DataEngineAggregateOptions, DataEngineAggregateRequest, DataEngineBatchRequest, DataEngineCountOptions, DataEngineCountRequest, DataEngineDeleteOptions, DataEngineDeleteRequest, DataEngineExecuteRequest, DataEngineFilter, DataEngineFindOneRequest, DataEngineFindRequest, DataEngineInsertOptions, DataEngineInsertRequest, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DataEngineUpdateRequest, DataEngineVectorFindRequest } from '@objectstack/spec/data';
26-
import type { DataEngineAggregateOptions, DataEngineAggregateRequest, DataEngineBatchRequest, DataEngineCountOptions, DataEngineCountRequest, DataEngineDeleteOptions, DataEngineDeleteRequest, DataEngineExecuteRequest, DataEngineFilter, DataEngineFindOneRequest, DataEngineFindRequest, DataEngineInsertOptions, DataEngineInsertRequest, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DataEngineUpdateRequest, DataEngineVectorFindRequest } from '@objectstack/spec/data';
25+
import { BaseEngineOptions, DataEngineAggregateOptions, DataEngineAggregateRequest, DataEngineBatchRequest, DataEngineCountOptions, DataEngineCountRequest, DataEngineDeleteOptions, DataEngineDeleteRequest, DataEngineExecuteRequest, DataEngineFilter, DataEngineFindOneRequest, DataEngineFindRequest, DataEngineInsertOptions, DataEngineInsertRequest, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DataEngineUpdateRequest, DataEngineVectorFindRequest } from '@objectstack/spec/data';
26+
import type { BaseEngineOptions, DataEngineAggregateOptions, DataEngineAggregateRequest, DataEngineBatchRequest, DataEngineCountOptions, DataEngineCountRequest, DataEngineDeleteOptions, DataEngineDeleteRequest, DataEngineExecuteRequest, DataEngineFilter, DataEngineFindOneRequest, DataEngineFindRequest, DataEngineInsertOptions, DataEngineInsertRequest, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DataEngineUpdateRequest, DataEngineVectorFindRequest } from '@objectstack/spec/data';
2727

2828
// Validate data
29-
const result = DataEngineAggregateOptions.parse(data);
29+
const result = BaseEngineOptions.parse(data);
3030
```
3131

32+
---
33+
34+
## BaseEngineOptions
35+
36+
### Properties
37+
38+
| Property | Type | Required | Description |
39+
| :--- | :--- | :--- | :--- |
40+
| **context** | `Object` | optional | |
41+
42+
3243
---
3344

3445
## DataEngineAggregateOptions
@@ -39,6 +50,7 @@ Options for DataEngine.aggregate operations
3950

4051
| Property | Type | Required | Description |
4152
| :--- | :--- | :--- | :--- |
53+
| **context** | `Object` | optional | |
4254
| **filter** | `Record<string, any> \| [__schema0](./__schema0)` | optional | Data Engine query filter conditions |
4355
| **groupBy** | `string[]` | optional | |
4456
| **aggregations** | `Object[]` | optional | |
@@ -80,6 +92,7 @@ Options for DataEngine.count operations
8092

8193
| Property | Type | Required | Description |
8294
| :--- | :--- | :--- | :--- |
95+
| **context** | `Object` | optional | |
8396
| **filter** | `Record<string, any> \| [__schema0](./__schema0)` | optional | Data Engine query filter conditions |
8497

8598

@@ -106,6 +119,7 @@ Options for DataEngine.delete operations
106119

107120
| Property | Type | Required | Description |
108121
| :--- | :--- | :--- | :--- |
122+
| **context** | `Object` | optional | |
109123
| **filter** | `Record<string, any> \| [__schema0](./__schema0)` | optional | Data Engine query filter conditions |
110124
| **multi** | `boolean` | optional | |
111125

@@ -196,6 +210,7 @@ Options for DataEngine.insert operations
196210

197211
| Property | Type | Required | Description |
198212
| :--- | :--- | :--- | :--- |
213+
| **context** | `Object` | optional | |
199214
| **returning** | `boolean` | optional | |
200215

201216

@@ -223,6 +238,7 @@ Query options for IDataEngine.find() operations
223238

224239
| Property | Type | Required | Description |
225240
| :--- | :--- | :--- | :--- |
241+
| **context** | `Object` | optional | |
226242
| **filter** | `Record<string, any> \| [__schema0](./__schema0)` | optional | Data Engine query filter conditions |
227243
| **select** | `string[]` | optional | |
228244
| **sort** | `Record<string, Enum<'asc' \| 'desc'>> \| Record<string, number \| number> \| Object[]` | optional | Sort order definition |
@@ -410,6 +426,7 @@ Options for DataEngine.update operations
410426

411427
| Property | Type | Required | Description |
412428
| :--- | :--- | :--- | :--- |
429+
| **context** | `Object` | optional | |
413430
| **filter** | `Record<string, any> \| [__schema0](./__schema0)` | optional | Data Engine query filter conditions |
414431
| **upsert** | `boolean` | optional | |
415432
| **multi** | `boolean` | optional | |

‎content/docs/references/kernel/execution-context.mdx‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: Execution Context
3+
description: Execution Context protocol schemas
4+
---
5+
6+
Execution Context Schema
7+
8+
Defines the runtime context that flows from HTTP request → data operations.
9+
10+
This is the "identity + environment" envelope that every data operation can carry.
11+
12+
Design:
13+
14+
- All fields are optional for backward compatibility
15+
16+
- `isSystem` bypasses permission checks (for internal/migration operations)
17+
18+
- `transaction` carries the database transaction handle for atomicity
19+
20+
- `traceId` enables distributed tracing across microservices
21+
22+
Usage:
23+
24+
engine.find('account', { context: { userId: '...', tenantId: '...' } })
25+
26+
<Callout type="info">
27+
**Source:** `packages/spec/src/kernel/execution-context.zod.ts`
28+
</Callout>
29+
30+
## TypeScript Usage
31+
32+
```typescript
33+
import { ExecutionContext } from '@objectstack/spec/kernel';
34+
import type { ExecutionContext } from '@objectstack/spec/kernel';
35+
36+
// Validate data
37+
const result = ExecutionContext.parse(data);
38+
```
39+
40+
---
41+
42+
## ExecutionContext
43+
44+
### Properties
45+
46+
| Property | Type | Required | Description |
47+
| :--- | :--- | :--- | :--- |
48+
| **userId** | `string` | optional | |
49+
| **tenantId** | `string` | optional | |
50+
| **roles** | `string[]` | ✅ | |
51+
| **permissions** | `string[]` | ✅ | |
52+
| **isSystem** | `boolean` | ✅ | |
53+
| **accessToken** | `string` | optional | |
54+
| **transaction** | `any` | optional | |
55+
| **traceId** | `string` | optional | |
56+
57+
58+
---
59+

‎content/docs/references/kernel/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ This section contains all protocol schemas for the kernel layer of ObjectStack.
88
<Cards>
99
<Card href="/docs/references/kernel/context" title="Context" description="Source: packages/spec/src/kernel/context.zod.ts" />
1010
<Card href="/docs/references/kernel/events" title="Events" description="Source: packages/spec/src/kernel/events.zod.ts" />
11+
<Card href="/docs/references/kernel/execution-context" title="Execution Context" description="Source: packages/spec/src/kernel/execution-context.zod.ts" />
1112
<Card href="/docs/references/kernel/feature" title="Feature" description="Source: packages/spec/src/kernel/feature.zod.ts" />
1213
<Card href="/docs/references/kernel/manifest" title="Manifest" description="Source: packages/spec/src/kernel/manifest.zod.ts" />
1314
<Card href="/docs/references/kernel/metadata-loader" title="Metadata Loader" description="Source: packages/spec/src/kernel/metadata-loader.zod.ts" />

‎content/docs/references/kernel/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
"pages": [
44
"context",
55
"events",
6+
"execution-context",
67
"feature",
78
"manifest",
89
"metadata-persistence",

0 commit comments

Comments
 (0)