Skip to main content

​
API Clients

The core package provides type-safe API clients built on top of the ky HTTP library with Zod schema validation.

​
Authentication (Legacy)

​
authRepositories

Legacy authentication client for token-based authentication. Location: @workspace/core/apis/auth 
import { Http } from '@workspace/core/services/http'
import { authRepositories } from '@workspace/core/apis/auth'

const http = new Http({ baseUrl: process.env.API_BASE_URL })
const auth = authRepositories(http)

​
login

Authenticate user with username and password. 
const result = await auth.login({
  json: {
    username: 'johndoe',
    password: 'password123',
    expiresInMins: 60, // optional
  },
})
​
json.username
string
required
Username (minimum 3 characters)
​
json.password
string
required
Password (minimum 6 characters)
​
json.expiresInMins
number
Token expiration time in minutes
​
id
number
User ID
​
username
string
Username
​
email
string
User email address
​
firstName
string
User’s first name
​
lastName
string
User’s last name
​
gender
'male' | 'female'
User’s gender
​
image
string
URL to user’s profile image
​
accessToken
string
JWT access token
​
refreshToken
string
JWT refresh token
Throws: HTTPError, TimeoutError, ZodError URL: POST ${env.apiBaseUrl}/auth/login

​
Better Auth

​
authRepositories

Modern authentication client using Better Auth library with session-based authentication. Location: @workspace/core/apis/better-auth 
import { Http } from '@workspace/core/services/http'
import { authRepositories } from '@workspace/core/apis/better-auth'

const http = new Http({ baseUrl: process.env.API_BASE_URL })
const auth = authRepositories(http)

​
getSession

Retrieve the current user session. 
const { headers, json } = await auth.getSession()

if (json) {
  console.log('User:', json.user.email)
  console.log('Session expires:', json.session.expiresAt)
}
​
session
AuthSessionSchema | null
Session information
​
user
AuthUserSchema | null
User information
Throws: HTTPError, TimeoutError, ZodError URL: GET ${env.apiBaseUrl}/api/auth/get-session

​
signInEmail

Sign in user with email and password. 
const { headers, json } = await auth.signInEmail({
  json: {
    email: '[email protected]',
    password: 'securepassword',
    rememberMe: true,
    callbackURL: '/dashboard',
  },
})
​
json.email
string
required
User’s email address
​
json.password
string
required
User’s password (minimum 8 characters)
​
json.rememberMe
boolean
Whether to create a persistent session
​
json.callbackURL
string
URL to redirect after successful sign in
​
redirect
boolean
Whether to perform a redirect
​
token
string
Authentication token
​
url
string | null
Redirect URL
Throws: HTTPError, TimeoutError, ZodError URL: POST ${env.apiBaseUrl}/api/auth/sign-in/email

​
signUpEmail

Register a new user with email and password. 
const { headers, json } = await auth.signUpEmail({
  json: {
    email: '[email protected]',
    password: 'securepassword',
    name: 'John Doe',
    callbackURL: '/welcome',
  },
})
​
json.email
string
required
User’s email address
​
json.password
string
required
User’s password (minimum 8 characters)
​
json.name
string
required
User’s full name (minimum 3 characters)
​
json.callbackURL
string
URL to redirect after successful registration
​
token
string | null
Verification token (if email verification is enabled)
Throws: HTTPError, TimeoutError, ZodError URL: POST ${env.apiBaseUrl}/api/auth/sign-up/email

​
signOut

Sign out the current user. 
const { headers, json } = await auth.signOut()

if (json.success) {
  // Redirect to login page
}
​
success
boolean
Whether sign out was successful
Throws: HTTPError, TimeoutError, ZodError URL: POST ${env.apiBaseUrl}/api/auth/sign-out

​
CDN

​
cdnRepositories

Client for fetching files from CDN or external URLs. Location: @workspace/core/apis/cdn 
import { cdnRepositories } from '@workspace/core/apis/cdn'

const cdn = cdnRepositories()

​
getCdnFile

Fetch a file from a CDN URL. 
const { response, blob, headers } = await cdn.getCdnFile({
  url: 'https://cdn.example.com/images/photo.jpg',
})

// Create object URL for display
const objectUrl = URL.createObjectURL(blob)
​
url
string
required
Full URL to the CDN file
​
options
Options
Optional Ky request options (timeout, headers, etc.)
​
response
KyResponse
The full Ky response object
​
blob
Blob
File contents as a Blob
​
headers
Record<string, string>
Response headers as key-value object
Throws: HTTPError, TimeoutError URL: GET ${url}

​
Core API Schemas

​
Common Schemas

Shared schemas used across API clients. Location: @workspace/core/apis/core

​
ErrorResponseSchema

Standard error response format. 
import type { ErrorResponseSchema } from '@workspace/core/apis/core'

interface ErrorResponseSchema {
  message: string
}

​
ResourceListRequestSchema

Pagination and filtering parameters for list endpoints. 
import type { ResourceListRequestSchema } from '@workspace/core/apis/core'

interface ResourceListRequestSchema {
  limit?: number    // 1-100, limit per page
  skip?: number     // Skip first n items
  select?: string   // Comma-separated field names
  delay?: number    // Artificial delay in ms (for testing)
}

​
ResourceListResponseSchema

Standard pagination metadata in list responses. 
import type { ResourceListResponseSchema } from '@workspace/core/apis/core'

interface ResourceListResponseSchema {
  total: number   // Total number of items
  skip: number    // Number of items skipped
  limit: number   // Items per page
}

​
Query Keys

All API clients export query key factories for use with React Query: 
import { authKeys } from '@workspace/core/apis/better-auth'
import { cdnKeys } from '@workspace/core/apis/cdn'

// Generate query keys
const sessionKey = authKeys.all()  // ['auth']
const signInKey = authKeys.signInEmail({ email: '[email protected]' })
// ['auth', 'signInEmail', { email: '[email protected]' }]

const cdnKey = cdnKeys.getArticleCoverImage('https://...')
// ['cdn', 'article', 'https://...']

Build docs developers (and LLMs) love

Get started for freeTalk to us