Skip to main content

​
Overview

The Core Package provides API client modules for interacting with backend services. All API clients are built on top of the HTTP service using the ky library for type-safe HTTP requests.

​
Authentication API

The authentication API provides methods for user authentication operations including sign-up, sign-in, sign-out, and session management.

​
Import

import { authRepositories } from '@workspace/core/apis/auth';
import { Http } from '@workspace/core/services/http';

​
Usage

const http = new Http({
  prefixUrl: 'https://api.example.com',
  credentials: 'include'
});

const auth = authRepositories(http);

​
Types & Schemas

​
AuthSessionSchema

Represents an authenticated user session.
​
id
string
required
Unique session identifier
​
expiresAt
string (date)
required
ISO 8601 date string when the session expires
​
token
string
required
Session authentication token
​
createdAt
string (date)
required
ISO 8601 date string when the session was created
​
updatedAt
string (date)
required
ISO 8601 date string when the session was last updated
​
ipAddress
string
required
IP address associated with the session
​
userAgent
string
required
User agent string from the client
​
userId
string
required
ID of the user who owns this session

​
AuthUserSchema

Represents a user account.
​
id
string
required
Unique user identifier
​
name
string
required
User’s display name
​
email
string (email)
required
User’s email address
​
emailVerified
boolean
required
Whether the user’s email has been verified
​
image
string | null
required
URL to user’s profile image, or null if not set
​
createdAt
string (date)
required
ISO 8601 date string when the user was created
​
updatedAt
string (date)
required
ISO 8601 date string when the user was last updated

​
API Methods

​
getSession

Retrieves the current authenticated session.
​
options
Options
Ky request options for customizing the HTTP request
​
session
AuthSessionSchema
The current session object
​
user
AuthUserSchema
The authenticated user object
​
headers
Headers
Response headers from the HTTP request
URL: GET /api/auth/get-session Access: Public Throws: HTTPError | TimeoutError | ZodError 
const { json, headers } = await auth.getSession();

if (json) {
  console.log('User:', json.user.name);
  console.log('Session expires:', json.session.expiresAt);
} else {
  console.log('Not authenticated');
}

​
signInEmail

Sign in a user with email and password.
​
options.json
AuthSignInEmailRequestSchema
required
Request body containing sign-in credentials
​
options.json.email
string (email)
required
User’s email address
​
options.json.password
string
required
User’s password (minimum 8 characters)
​
options.json.rememberMe
boolean
required
Whether to create a persistent session
​
options.json.callbackURL
string
URL to redirect to after successful sign-in
​
json.redirect
boolean
Whether a redirect should be performed
​
json.token
string
Authentication token for the session
​
json.url
string | null
URL to redirect to, or null if no redirect
​
headers
Headers
Response headers from the HTTP request
URL: POST /api/auth/sign-in/email Access: Public Throws: HTTPError | TimeoutError | ZodError 
const { json, headers } = await auth.signInEmail({
  json: {
    email: '[email protected]',
    password: 'SecurePassword123',
    rememberMe: true,
    callbackURL: '/dashboard'
  }
});

if (json.redirect && json.url) {
  window.location.href = json.url;
}

​
signUpEmail

Register a new user with email and password.
​
options.json
AuthSignUpEmailRequestSchema
required
Request body containing registration details
​
options.json.email
string (email)
required
User’s email address
​
options.json.password
string
required
User’s password (minimum 8 characters)
​
options.json.name
string
required
User’s display name (minimum 3 characters)
​
options.json.callbackURL
string
URL to redirect to after successful sign-up
​
json.token
string | null
Authentication token if registration is successful, null otherwise
​
headers
Headers
Response headers from the HTTP request
URL: POST /api/auth/sign-up/email Access: Public Throws: HTTPError | TimeoutError | ZodError 
const { json, headers } = await auth.signUpEmail({
  json: {
    email: '[email protected]',
    password: 'SecurePassword123',
    name: 'John Doe',
    callbackURL: '/welcome'
  }
});

if (json.token) {
  console.log('Registration successful!');
}

​
signOut

Sign out the current user and invalidate their session.
​
options
Options
Ky request options for customizing the HTTP request
​
json.success
boolean
Whether the sign-out was successful
​
headers
Headers
Response headers from the HTTP request
URL: POST /api/auth/sign-out Access: Public Throws: HTTPError | TimeoutError | ZodError 
const { json, headers } = await auth.signOut();

if (json.success) {
  console.log('Successfully signed out');
  window.location.href = '/login';
}

​
Query Keys

For use with TanStack Query or similar data-fetching libraries: 
import { authKeys } from '@workspace/core/apis/auth';

// All auth-related queries
authKeys.all(); // ['auth']

// Sign-up email query
authKeys.signUpEmail({
  email: '[email protected]',
  password: 'password',
  name: 'John'
}); // ['auth', 'signUpEmail', { email: '...', password: '...', name: '...' }]

// Sign-in email query
authKeys.signInEmail({
  email: '[email protected]',
  password: 'password',
  rememberMe: true
}); // ['auth', 'signInEmail', { email: '...', password: '...', rememberMe: true }]

// Sign-out query
authKeys.signOut(); // ['auth', 'signOut']

​
Constants

const AUTH_PASSWORD_MIN_LENGTH = 8;
const AUTH_NAME_MIN_LENGTH = 3;

​
Error Handling

All API methods can throw the following errors:
  • HTTPError: HTTP request failed (4xx or 5xx status codes)
  • TimeoutError: Request exceeded timeout limit
  • ZodError: Response validation failed
import { HTTPError, TimeoutError } from 'ky';
import { ZodError } from 'zod';

try {
  const { json } = await auth.signInEmail({
    json: { email, password, rememberMe: true }
  });
} catch (error) {
  if (error instanceof HTTPError) {
    console.error('HTTP Error:', error.response.status);
  } else if (error instanceof TimeoutError) {
    console.error('Request timeout');
  } else if (error instanceof ZodError) {
    console.error('Invalid response:', error.errors);
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us