⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.
TypeScript agenticagileai-agentsbug-reportingbug-trackerganttissue-trackerjirajira-alternativekanbanlinearlinear-alternativeopen-sourceproduct-managementproject-managementroadmapself-hostedsprint-planningteam-collaborationtrello-alternative
import { request } from '@/lib/api/core/client';
import type { MemberRole } from '@/lib/api/endpoints/members';
import type { TeamRole } from '@/lib/api/endpoints/teams';
import type { NotificationEncryption } from '@/lib/api/endpoints/notificationSettings';
import type { Permissions, Role } from '@/lib/api/endpoints/roles';
import type { ProjectDefaults } from '@/lib/api/endpoints/projects';
import type {
HotkeyOverrides,
StorageSettings,
StorageSettingsPatch,
} from '@/lib/api/endpoints/settings';
import { pageQuery, type Page, type PageParams } from '@/lib/api/core/paging';
// Who may create an account on this instance.
export type RegistrationMode = 'open' | 'invite' | 'closed';
// The instance sign-in policy. hasEmailProvider tells whether outbound mail works;
// the options that depend on it cannot be turned on without one.
export interface InstanceAuthSettings {
registration: RegistrationMode;
requireEmailVerification: boolean;
magicLink: boolean;
emailPassword: boolean;
trustProviderEmails: boolean;
personalWorkspaces: boolean;
// Days an invite link stays valid; 0 means invites never expire.
inviteTtlDays: number;
inviteSearch: boolean;
// The domains a new account's address must be at; empty admits any address.
allowedEmailDomains: string[];
hasEmailProvider: boolean;
// Whether Google or the OIDC provider can run. Password sign-in may only be turned
// off while one of them can.
hasSsoProvider: boolean;
}
export interface InstanceAuthSettingsPatch {
registration?: RegistrationMode;
requireEmailVerification?: boolean;
magicLink?: boolean;
emailPassword?: boolean;
trustProviderEmails?: boolean;
personalWorkspaces?: boolean;
inviteTtlDays?: number;
inviteSearch?: boolean;
allowedEmailDomains?: string[];
}
// 'microsoft365' signs in to smtp.office365.com as an app registration (OAuth) instead
// of with the mailbox password, which Microsoft refuses once the mailbox has MFA.
export type SmtpAuth = 'password' | 'microsoft365';
// The instance mail provider used for authentication email (password reset, address
// verification, magic links). Separate from a team's notification provider.
// Secrets are never returned, only a `hasX` flag.
export interface InstanceEmailSettings {
smtp: {
enabled: boolean;
host: string;
port: number | null;
encryption: NotificationEncryption;
username: string;
hasPassword: boolean;
timeout: number | null;
auth: SmtpAuth;
oauth: { tenantId: string; clientId: string; hasClientSecret: boolean };
};
resend: { enabled: boolean; hasApiKey: boolean };
from: string;
// Whether projects may deliver their notifications through this provider.
allowProjects: boolean;
}
export interface InstanceEmailSettingsPatch {
smtp?: {
enabled: boolean;
host: string;
port: number | null;
encryption: NotificationEncryption;
username: string;
password?: string;
timeout: number | null;
auth?: SmtpAuth;
oauth?: { tenantId: string; clientId: string; clientSecret?: string };
};
resend?: { enabled: boolean; apiKey?: string };
from?: string;
allowProjects?: boolean;
}
export interface InstanceEmailTestResult {
recipient: string;
}
// The Google OAuth credentials used for social sign-in. The client secret is never
// returned, only a `hasClientSecret` flag. redirectUri is derived from the API origin
// and has to be registered in the Google Cloud console.
export interface InstanceGoogleSettings {
enabled: boolean;
clientId: string;
hasClientSecret: boolean;
redirectUri: string;
}
export interface InstanceGoogleSettingsPatch {
enabled?: boolean;
clientId?: string;
clientSecret?: string;
}
// The instance's generic OIDC/OAuth2 provider. The client secret is never returned,
// only a `hasClientSecret` flag. redirectUri is derived from the API origin and has
// to be registered with the identity provider.
export interface InstanceOidcSettings {
enabled: boolean;
label: string;
discoveryUrl: string;
clientId: string;
hasClientSecret: boolean;
scopes: string[];
pkce: boolean;
redirectUri: string;
}
export interface InstanceOidcSettingsPatch {
enabled?: boolean;
label?: string;
discoveryUrl?: string;
clientId?: string;
clientSecret?: string;
scopes?: string[];
pkce?: boolean;
}
// The instance Telegram bot: the one bot users link their accounts through, and the
// default sender for Telegram notifications. `botUsername` is resolved from Telegram
// when the token is saved.
export interface InstanceTelegramSettings {
enabled: boolean;
botUsername: string;
hasBotToken: boolean;
}
export interface InstanceTelegramSettingsPatch {
enabled?: boolean;
botToken?: string;
}
// One account in the instance user directory. `role` is the global better-auth role
// ("god" for the instance owner), which is unrelated to project membership.
export interface InstanceUser {
id: string;
name: string;
email: string;
image: string | null;
emailVerified: boolean;
role: string;
isAgent: boolean;
providers: string[];
projectCount: number;
active: boolean;
// Why god cannot switch `active`, or null when it can.
activeLock: 'owner' | 'agent' | 'scim' | null;
lastSeenAt: string | null;
createdAt: string;
}
// A project the user can reach, with the permissions their membership resolves to
// (full for an owner, the assigned role's matrix for a member).
export interface InstanceUserProject {
projectId: number;
projectKey: string;
projectName: string;
role: MemberRole;
roleId: number | null;
roleName: string | null;
permissions: Permissions;
// How many owners the project has. 1 on a project this user owns means deleting
// the account would leave the project with nobody who can manage it, unless it is in a
// workspace of theirs.
ownerCount: number;
// In a workspace this user owns: it passes to the instance owner with the account.
inOwnWorkspace: boolean;
joinedAt: string;
}
export interface InstanceUserDetail extends InstanceUser {
projects: InstanceUserProject[];
}
// Which accounts the directory lists: real people, the bot users behind AI agents,
// or both.
export type InstanceUserKind = 'human' | 'agent' | 'all';
// One project in the instance project directory, with what it holds counted across
// its dependent tables. `lastActivityAt` is the most recent entry in its issue feed.
export interface InstanceProject {
id: number;
key: string;
name: string;
description: string;
mcpEnabled: boolean;
memberCount: number;
issueCount: number;
archivedIssueCount: number;
initiativeCount: number;
dashboardCount: number;
viewCount: number;
agentCount: number;
skillCount: number;
toolCount: number;
lastActivityAt: string | null;
createdAt: string;
}
// One member of a project, with the permissions their membership resolves to (full
// for an owner, the assigned role's matrix for a member).
export interface InstanceProjectMember {
userId: string;
name: string;
email: string;
username: string | null;
image: string | null;
isAgent: boolean;
role: MemberRole;
roleId: number | null;
roleName: string | null;
permissions: Permissions;
description: string;
timezone: string;
joinedAt: string;
}
export interface InstanceProjectDetail extends InstanceProject {
members: InstanceProjectMember[];
}
// Instance administration (god mode). Every route below is owner-only; a plain
// user gets a 403, which is why the entries are hidden from the sidebar.
export const getInstanceAuthSettings = () => request<InstanceAuthSettings>('/god/auth-settings');
export const updateInstanceAuthSettings = (patch: InstanceAuthSettingsPatch) =>
request<InstanceAuthSettings>('/god/auth-settings', {
method: 'PUT',
body: JSON.stringify(patch),
});
export const getInstanceEmailSettings = () => request<InstanceEmailSettings>('/god/email-settings');
export const updateInstanceEmailSettings = (patch: InstanceEmailSettingsPatch) =>
request<InstanceEmailSettings>('/god/email-settings', {
method: 'PUT',
body: JSON.stringify(patch),
});
export const testInstanceEmailSettings = (patch: InstanceEmailSettingsPatch) =>
request<InstanceEmailTestResult>('/god/email-settings/test', {
method: 'POST',
body: JSON.stringify(patch),
});
export interface EmailText {
subject: string;
body: string;
button: string;
}
export interface EmailLayout {
html: string;
css: string;
}
export interface EmailTemplateEntry {
key: string;
group: string;
variables: string[];
hasLink: boolean;
defaults: Record<string, EmailText>;
edits: Record<string, EmailText>;
}
export interface EmailTemplatesSettings {
templates: EmailTemplateEntry[];
layout: EmailLayout;
defaultLayout: EmailLayout;
placeholders: { name: string; required: boolean }[];
canSend: boolean;
}
export interface EmailTemplatesBody {
edits: Record<string, Record<string, EmailText>>;
layout: EmailLayout | null;
}
export interface EmailDraft {
key: string;
locale: string;
text: EmailText;
layout: EmailLayout;
}
export interface EmailPreview {
subject: string;
text: string;
html: string;
from: string | null;
}
export const getEmailTemplates = () => request<EmailTemplatesSettings>('/god/email-templates');
export const updateEmailTemplates = (body: EmailTemplatesBody) =>
request<EmailTemplatesSettings>('/god/email-templates', {
method: 'PUT',
body: JSON.stringify(body),
});
export const previewEmailDraft = (draft: EmailDraft) =>
request<EmailPreview>('/god/email-templates/preview', {
method: 'POST',
body: JSON.stringify(draft),
});
export const testEmailDraft = (draft: EmailDraft) =>
request<InstanceEmailTestResult>('/god/email-templates/test', {
method: 'POST',
body: JSON.stringify(draft),
});
export const getInstanceTelegramSettings = () =>
request<InstanceTelegramSettings>('/god/telegram-settings');
export const updateInstanceTelegramSettings = (patch: InstanceTelegramSettingsPatch) =>
request<InstanceTelegramSettings>('/god/telegram-settings', {
method: 'PUT',
body: JSON.stringify(patch),
});
export const getInstanceHotkeySettings = () => request<HotkeyOverrides>('/god/hotkey-settings');
export const updateInstanceHotkeySettings = (combos: HotkeyOverrides) =>
request<HotkeyOverrides>('/god/hotkey-settings', {
method: 'PUT',
body: JSON.stringify(combos),
});
export const getInstanceProjectDefaults = () => request<ProjectDefaults>('/god/project-defaults');
export const updateInstanceProjectDefaults = (body: ProjectDefaults) =>
request<ProjectDefaults>('/god/project-defaults', {
method: 'PUT',
body: JSON.stringify(body),
});
// What applies to every team's agents on this instance.
export interface AgentSettings {
// Days a run trace is kept for. 0 keeps traces until they are deleted by hand.
traceRetentionDays: number;
// Seconds one agent run may take; an agent's own limit cannot exceed it.
maxRunSeconds: number;
// Runs of internal agents in flight at once across the instance. 0 sets no limit.
maxConcurrentRuns: number;
}
export const getInstanceAgentSettings = () => request<AgentSettings>('/god/agent-settings');
export const updateInstanceAgentSettings = (body: Partial<AgentSettings>) =>
request<AgentSettings>('/god/agent-settings', {
method: 'PUT',
body: JSON.stringify(body),
});
// Whether public links work on this instance.
export interface SharingSettings {
enabled: boolean;
}
export const getInstanceSharingSettings = () => request<SharingSettings>('/god/sharing-settings');
export const updateInstanceSharingSettings = (body: SharingSettings) =>
request<SharingSettings>('/god/sharing-settings', {
method: 'PUT',
body: JSON.stringify(body),
});
// The sites that may show the shared work items and views, and the public pages, in a frame.
export interface EmbedSites {
origins: string[];
}
export const getInstanceEmbedSites = () => request<EmbedSites>('/god/embed-sites');
export const updateInstanceEmbedSites = (origins: string[]) =>
request<EmbedSites>('/god/embed-sites', {
method: 'PUT',
body: JSON.stringify({ origins }),
});
export const getInstanceStorageSettings = () => request<StorageSettings>('/god/storage-settings');
export const updateInstanceStorageSettings = (patch: StorageSettingsPatch) =>
request<StorageSettings>('/god/storage-settings', {
method: 'PUT',
body: JSON.stringify(patch),
});
export const getInstanceGoogleSettings = () =>
request<InstanceGoogleSettings>('/god/google-settings');
export const updateInstanceGoogleSettings = (patch: InstanceGoogleSettingsPatch) =>
request<InstanceGoogleSettings>('/god/google-settings', {
method: 'PUT',
body: JSON.stringify(patch),
});
export const getInstanceOidcSettings = () => request<InstanceOidcSettings>('/god/oidc-settings');
export const updateInstanceOidcSettings = (patch: InstanceOidcSettingsPatch) =>
request<InstanceOidcSettings>('/god/oidc-settings', {
method: 'PUT',
body: JSON.stringify(patch),
});
// The instance user directory: one page of accounts, and one account with the
// projects it can reach. Search, the kind filter and paging all run on the server.
export const listInstanceUsers = (
params: PageParams & { search?: string; kind: InstanceUserKind },
) =>
request<Page<InstanceUser>>(
`/god/users${pageQuery(params, { kind: params.kind, search: params.search })}`,
);
export const getInstanceUser = (userId: string) =>
request<InstanceUserDetail>(`/god/users/${userId}`);
export const setInstanceUserActive = (userId: string, active: boolean) =>
request<InstanceUserDetail>(`/god/users/${userId}/${active ? 'reactivate' : 'deactivate'}`, {
method: 'POST',
});
export const verifyInstanceUserEmail = (userId: string) =>
request<InstanceUserDetail>(`/god/users/${userId}/verify-email`, { method: 'POST' });
// `withProjects` takes down the projects the user owns alone; without it the API
// refuses to delete an account that would leave a project ownerless.
export const deleteInstanceUser = (userId: string, withProjects: boolean) =>
request<void>(`/god/users/${userId}${withProjects ? '?withProjects=true' : ''}`, {
method: 'DELETE',
});
// The instance project directory: one page of projects, and one project with its
// members. Search and paging run on the server.
export const listInstanceProjects = (params: PageParams & { search?: string }) =>
request<Page<InstanceProject>>(`/god/projects${pageQuery(params, { search: params.search })}`);
export const getInstanceProject = (projectId: number) =>
request<InstanceProjectDetail>(`/god/projects/${projectId}`);
// One team in the instance team directory, with what it holds counted across the
// tables the team owns and the projects it owns.
export interface InstanceTeam {
id: number;
name: string;
mcpEnabled: boolean;
memberCount: number;
projectCount: number;
issueCount: number;
agentCount: number;
skillCount: number;
toolCount: number;
roleCount: number;
createdAt: string;
}
// One project the team owns, as the team panel lists it.
export interface InstanceTeamProject {
id: number;
key: string;
name: string;
mcpEnabled: boolean;
memberCount: number;
issueCount: number;
createdAt: string;
}
// One member of a team. The role is the fixed team rank ('owner', 'manager',
// 'member', 'agent'), not a project role.
export interface InstanceTeamMember {
userId: string;
name: string;
email: string;
image: string | null;
isAgent: boolean;
role: TeamRole | 'agent';
joinedAt: string;
}
// The instance team directory: one page of teams, and one team with its counts. The
// projects and the members of a team are paged apart, so a large team is never
// loaded whole.
export const listInstanceTeams = (params: PageParams & { search?: string }) =>
request<Page<InstanceTeam>>(`/god/teams${pageQuery(params, { search: params.search })}`);
export const getInstanceTeam = (teamId: number) => request<InstanceTeam>(`/god/teams/${teamId}`);
export const listInstanceTeamProjects = (
teamId: number,
params: PageParams & { search?: string },
) =>
request<Page<InstanceTeamProject>>(
`/god/teams/${teamId}/projects${pageQuery(params, { search: params.search })}`,
);
export const listInstanceTeamMembers = (teamId: number, params: PageParams & { search?: string }) =>
request<Page<InstanceTeamMember>>(
`/god/teams/${teamId}/members${pageQuery(params, { search: params.search })}`,
);
// System roles: permission matrices that belong to no team, written only in god mode.
export const listSystemRoles = () => request<Role[]>('/god/roles');
export const createSystemRole = (input: { name: string; permissions: Permissions }) =>
request<Role>('/god/roles', { method: 'POST', body: JSON.stringify(input) });
export const updateSystemRole = (
roleId: number,
patch: { name?: string; permissions?: Permissions },
) => request<Role>(`/god/roles/${roleId}`, { method: 'PATCH', body: JSON.stringify(patch) });
export const deleteSystemRole = (roleId: number) =>
request<void>(`/god/roles/${roleId}`, { method: 'DELETE' });