docyrus-api-dev

What this skill does

# Docyrus API Developer

Integrate with the Docyrus API using `@docyrus/api-client` (REST client) and `@docyrus/signin` (React auth provider). Authenticate via OAuth2 PKCE, query data sources with powerful filtering/aggregation, and consume REST endpoints.

## Authentication Quick Start

### React Apps — Use @docyrus/signin

```tsx
import { DocyrusAuthProvider, useDocyrusAuth, useDocyrusClient, SignInButton } from '@docyrus/signin'

// 1. Wrap root
<DocyrusAuthProvider
  apiUrl={import.meta.env.VITE_API_BASE_URL}
  clientId={import.meta.env.VITE_OAUTH2_CLIENT_ID}
  redirectUri={import.meta.env.VITE_OAUTH2_REDIRECT_URI}
  scopes={['offline_access', 'Read.All', 'DS.ReadWrite.All', 'Users.Read']}
  callbackPath="/auth/callback"
>
  <App />
</DocyrusAuthProvider>

// 2. Use hooks
function App() {
  const { status, signOut } = useDocyrusAuth()
  const client = useDocyrusClient()  // RestApiClient | null

  if (status === 'loading') return <Spinner />
  if (status === 'unauthenticated') return <SignInButton />

  // client is ready — make API calls
  const user = await client!.get('/v1/users/me')
}
```

### Non-React / Server — Use OAuth2Client Directly

```typescript
import { RestApiClient, OAuth2Client, OAuth2TokenManagerAdapter, BrowserOAuth2TokenStorage } from '@docyrus/api-client'

const tokenStorage = new BrowserOAuth2TokenStorage(localStorage)
const oauth2 = new OAuth2Client({
  baseURL: 'https://api.docyrus.com',
  clientId: 'your-client-id',
  redirectUri: 'http://localhost:3000/callback',
  usePKCE: true,
  tokenStorage,
})

// Auth Code flow
const { url } = await oauth2.getAuthorizationUrl({ scope: 'openid offline_access Users.Read' })
window.location.href = url
// After redirect:
const tokens = await oauth2.handleCallback(window.location.href)

// Create API client with auto-refresh
const client = new RestApiClient({
  baseURL: 'https://api.docyrus.com',
  tokenManager: new OAuth2TokenManagerAdapter(tokenStorage, async () => {
    return (await oauth2.refreshAccessToken()).accessToken
  }),
})
```

## API Endpoints

### Data Source Items (Dynamic per tenant)
```
GET    /v1/apps/{appSlug}/data-sources/{slug}/items          — List with query payload
GET    /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Get one
POST   /v1/apps/{appSlug}/data-sources/{slug}/items          — Create
PATCH  /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Update
DELETE /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Delete one
DELETE /v1/apps/{appSlug}/data-sources/{slug}/items          — Delete many (body: { recordIds })
```

Endpoints exist only if the data source is defined in the tenant. Check the tenant's OpenAPI spec at `GET /v1/api/openapi.json`.

### System Endpoints (Always Available)
```
GET    /v1/users          — List users
POST   /v1/users          — Create user
GET    /v1/users/me       — Current user profile
PATCH  /v1/users/me       — Update current user
```

### Connector Discovery & External Request Endpoints
```
GET    /v1/connectors?q=&limit=&offset=                                    — List connectors with keyword search
GET    /v1/connectors/{dataProviderSlug}                                    — Get connector detail (dataSources + actions)
GET    /v1/connectors/{dataProviderSlug}/actions/{actionKey}                — Get action detail (input/output schemas, API endpoint)
GET    /v1/connectors/{dataProviderSlug}/connections                        — Get tenant connections + user connection status
PUT    /v1/connectors/{dataProviderSlug}                                    — Send HTTP request through connector provider auth
```

Scopes: `Read.All`, `ReadWrite.All`, or `Connectors.Read.All`. The `PUT` endpoint requires `ReadWrite.All`.

**PUT request body** for sending requests through a connector:
```json
{
  "endpoint": "relative/path/or/absolute-url",
  "requestMethod": "GET",
  "data": { "fields": "id,name", "limit": 20 },
  "contentType": "application/json",
  "headers": { "Authorization": "Bearer <override-token>" },
  "connectionId": "optional-tenant-connection-uuid",
  "connectionAccountId": "optional-connection-account-uuid"
}
```

The connector resolves auth credentials (OAuth tokens, base URL) from the provider configuration and stored connections. Custom `headers.Authorization` overrides the stored token.

### Action Run Endpoints
```
GET    /v1/apps/base/actions                                               — List base actions
GET    /v1/apps/{appSlug}/actions/{actionSlug}                             — Get action metadata
POST   /v1/apps/{appSlug}/actions/{actionSlug}/run                         — Run action directly
```

Action run accepts arbitrary JSON body as input. Optional headers: `x-connection-id`, `x-connection-account-id`.

### Studio (Dev) Schema Endpoints

The studio surface manages dev-app schema objects. Most routes are gated by the `Architect.Read.All` / `Architect.ReadWrite.All` scopes, and the app is identified by its tenant `app_id` UUID.

```
# Apps (mutations only — list uses /v1/apps)
DELETE /v1/dev/apps/{appId}                                                 — Archive app
POST   /v1/dev/apps/{appId}/restore                                         — Restore archived app
DELETE /v1/dev/apps/{appId}/permanent                                       — Permanently delete app

# Data sources
GET    /v1/dev/apps/{appId}/data-sources                                    — List data sources (?expand=fields,...)
GET    /v1/dev/apps/{appId}/data-sources/{dataSourceId}                     — Get data source
POST   /v1/dev/apps/{appId}/data-sources                                    — Create data source
PATCH  /v1/dev/apps/{appId}/data-sources/{dataSourceId}                     — Update data source
DELETE /v1/dev/apps/{appId}/data-sources/{dataSourceId}                     — Archive data source
POST   /v1/dev/apps/{appId}/data-sources/{dataSourceId}/restore             — Restore archived data source
DELETE /v1/dev/apps/{appId}/data-sources/{dataSourceId}/permanent           — Permanently delete data source
POST   /v1/dev/apps/{appId}/data-sources/bulk                               — Bulk create (body: { dataSources })

# Fields
GET    /v1/dev/apps/{appId}/data-sources/{dataSourceId}/fields                       — List fields
GET    /v1/dev/apps/{appId}/data-sources/{dataSourceId}/fields/{fieldId}             — Get field
POST   /v1/dev/apps/{appId}/data-sources/{dataSourceId}/fields                       — Create field
PATCH  /v1/dev/apps/{appId}/data-sources/{dataSourceId}/fields/{fieldId}             — Update field
DELETE /v1/dev/apps/{appId}/data-sources/{dataSourceId}/fields/{fieldId}             — Delete field
POST   /v1/dev/apps/{appId}/data-sources/{dataSourceId}/fields/batch                 — Bulk create (body: { fields })
PATCH  /v1/dev/apps/{appId}/data-sources/{dataSourceId}/fields/batch                 — Bulk update (body: { fields[].fieldId })
DELETE /v1/dev/apps/{appId}/data-sources/{dataSourceId}/fields/batch                 — Bulk delete (body: { fieldIds })

# Field enums
GET    /v1/dev/apps/{appId}/data-sources/{dataSourceId}/fields/{fieldId}/enums       — List enum options
POST   /v1/dev/apps/{appId}/data-sources/{dataSourceId}/fields/{fieldId}/enums       — Create enums (body: { enums })
PATCH  /v1/dev/apps/{appId}/data-sources/{dataSourceId}/fields/{fieldId}/enums       — Update enums (body: { enums[].enumId })
DELETE /v1/dev/apps/{appId}/data-sources/{dataSourceId}/fields/{fieldId}/enums       — Delete enums (body: { enumIds })

# Data views (saved views) — slug-scoped
GET    /v1/apps/{appSlug}/data-sources/{dataSourceSlug}/views                        — List views
GET    /v1/apps/{appSlug}/data-sources/{dataSourceSlug}/views/{viewId}               — Get view
POST   /v1/apps/{appSlug}/data-sources/{dataSourceSlug}/views                        — Create view
PUT    /v1/apps/{appSlug}/data-sources/{dataSourceSlug}/views/{viewId}               — Update view
DELETE /v1/apps/{appSlug}/data-sou