TypeScript SDK

npm install @pkg-projex/sdk
# or
pnpm add @pkg-projex/sdk
# or
yarn add @pkg-projex/sdk

import { ProjexClient } from '@pkg-projex/sdk';

// Recommended for CI / local scripts: configure via env only
const projex = new ProjexClient();

// Explicit overrides (win over env)
const staging = new ProjexClient({
  apiKey: process.env.PROJEX_API_KEY!,
  baseUrl: 'https://staging.example.com',
  timeoutMs: 45_000,
  maxRetries: 3,
});

# .env / shell
# Local ProjeX app/API origin
export PROJEX_API_URL="http://localhost:3000"
export PROJEX_API_KEY="pjx_live_…"

import { ProjexClient, ProjexApiError } from '@pkg-projex/sdk';

const projex = new ProjexClient();

try {
  // List methods return a page: { data, nextCursor }.
  const live = (await projex.cohorts.live()).data;
  if (!live.length) {
    throw new Error('No live cohorts for this account');
  }

  const milestones = (await projex.cohorts.milestones(live[0].id)).data;
  const milestone = milestones.find((m) => m.ref) ?? milestones[0];
  if (!milestone) {
    throw new Error('No milestones in cohort');
  }

  // Prefer a full T{team}M{ms} ref when available from your workflow.
  const ref = milestone.ref ?? milestone.id;

  const { submission } = await projex.milestones.submit(ref, {
    title: 'Sprint deliverable',
    submission: 'https://github.com/org/repo/pull/42',
  });

  console.log('Created submission', submission.id);
} catch (err) {
  if (err instanceof ProjexApiError) {
    console.error(err.status, err.code, err.message, err.requestId);
  }
  throw err;
}

type Page<T> = { data: T[]; nextCursor: string | null };

type Cohort = {
  id: string;                 // Stable cohort UUID — use with get / milestones / tasks
  name: string;               // Display name
  type: string | null;        // Cohort type when configured
  visibility: string | null;  // Visibility setting when configured
  startDate: string | null;   // ISO-8601 UTC
  endDate: string | null;     // ISO-8601 UTC
  status: 'planned' | 'live' | 'closed';
};

type CohortDetail = Cohort & {
  teams: Array<{
    id: string;        // Pass as teamId on milestone submit when needed
    publicId: number;  // Numeric team public id (used in T{{team}}M{{ms}} refs)
    name: string;
  }>;
};

type Milestone = {
  id: string;
  ref: string;                 // Directly submittable (e.g. "T12M3" or the id)
  publicId: number | null;
  title: string;
  description: string | null;
  order: number | null;
  startDate: string | null;    // Submission window start (ISO-8601)
  endDate: string | null;      // Submission window end (ISO-8601)
  submissionType: string | null;
};

type Task = {
  id: string;
  ref: string;                 // e.g. "TS42" — use with tasks.submit
  publicId: number;
  title: string;
  description: string | null;
  status: string;
  priority: string;
  milestoneId: string | null;
  deadline: string | null;     // ISO-8601 when set
};

{
  contributionAreaId?: string;  // Existing catalog area id
  customAreaName?: string;      // Free-text area when not using catalog
  breakdown: Array<{
    userId: string;             // Teammate user id
    percentage: number;         // Share for this area (typically 0–100)
  }>;
}

const { submission } = await projex.milestones.submit('T12M3', {
  title: 'Sprint 2 build',
  submission: 'https://github.com/me/proj/pull/12',
  teamId: 'optional-when-multi-team',
  contributionAreas: [
    {
      contributionAreaId: 'area-id',
      breakdown: [
        { userId: 'user-a', percentage: 60 },
        { userId: 'user-b', percentage: 40 },
      ],
    },
  ],
  reflectionAnswers: [
    { questionId: 'q1', answer: 'We validated the approach with mentors.' },
  ],
  replacesSubmissionId: 'previous-submission-id',
});

{
  submission: {
    id: string;
    teamId: string;
    milestoneId: string;
    userId: string;          // Submitter (API key owner)
    title: string;
    submission: string;
    redoAttempt?: number;    // Present when responding to a redo
    isRedo?: boolean;
    createdAt: string | Date;
    updatedAt: string | Date;
    // Additional team_submissions fields may be present
  }
}

// page.data entries (team_submissions rows):
{
  id: string;
  teamId: string;
  milestoneId: string;
  userId: string;
  title: string;
  submission: string;
  replacesSubmissionId: string | null;
  createdAt: string | Date;
}

const { submission } = await projex.tasks.submit('TS42', {
  title: 'Bugfix write-up',
  submission: '## Steps\n1. Reproduced on staging…',
});

// submission: {
//   id, taskId, submittedBy, title, submission, createdAt, …
// }

// page.data entries (task_submissions rows):
{
  id: string;
  taskId: string;
  submittedBy: string;
  title: string;
  submission: string;
  replacesSubmissionId: string | null;
  createdAt: string | Date;
}

const { uploadUrl, fileKey, publicUrl, expiresIn } =
  await projex.uploads.presign({
    fileName: 'report.pdf',
    contentType: 'application/pdf',
    size: 812345,
  });

// uploadUrl  — presigned PUT target; complete before expiresIn seconds
// fileKey    — e.g. submissions/<userId>/<uuid>/report.pdf
// publicUrl  — the file's URL once uploaded; usable directly as a submission
// expiresIn  — TTL in seconds (typically 3600)

await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'content-type': 'application/pdf' },
  body: fileBytes, // Buffer, Blob, or Uint8Array
});

// Then either attach it, or use publicUrl as the submission value:
await projex.milestones.submit(ref, {
  title: 'Report',
  submission: publicUrl,
  attachments: [{ fileKey, fileName: 'report.pdf' }],
});

import { ProjexClient } from '@pkg-projex/sdk';

const projex = new ProjexClient();

const cohort = await projex.cohorts.create({
  projectId: 'prj_123',
  name: 'Cohort 12',
  visibility: 'public',        // omitting this means "private" — see below
  startDate: '2026-08-01',
  endDate: '2026-10-01',
});

const team = await projex.teams.create(cohort.id, { name: 'Team Rocket' });

await projex.cohorts.members.add(cohort.id, {
  email: 'ada@example.com',
  role: 'learner',
  teamId: team.id,
});

type DeleteResult<T> =
  | { ok: true; deleted: T }     // it happened
  | { dryRun: true; impact: T }; // preview only, nothing was written

const preview = await projex.cohorts.delete(cohortId, { dryRun: true });
if ('impact' in preview) {
  console.log(preview.impact); // { teams: 4, members: 37, milestones: 6 }
}

type AdminCohort = Cohort & {
  projectId: string;
  clusterId: string | null;
};

// update(cohortId, input, opts?) — every field optional; only what you send changes.
// Accepts: name, visibility, clusterId, startDate, endDate.
await projex.cohorts.update(cohortId, { name: 'Cohort 12 (Autumn)' });

// delete(cohortId, opts?) — soft, and it cascades to the cohort's teams,
// members, milestones and submissions. Preview it first.
await projex.cohorts.delete(cohortId);
// → { ok: true, deleted: { teams: 4, members: 37, milestones: 6 } }

await projex.cohorts.members.add(cohortId, {
  email: 'ada@example.com',  // required — the identifier for every member call
  role: 'manager' | 'mentor' | 'evaluator' | 'learner',  // default: learner
  name: 'Ada Lovelace',      // used only if the user has to be created
  teamId: 'team_1',          // optional placement; without it a learner is team-less
  notify: true,              // onboarding email, newly created users only
});
// → {
//     userId, cohortMemberId, role, team: { id, name } | null,
//     created: { user, orgMember, cohortMember, teamMember },  // all booleans
//   }

// Changes the cohort role. Never deletes work, but it does reshuffle team
// placement — cohort role is the source of truth for which roster you sit on.
await projex.cohorts.members.changeRole(cohortId, {
  email: 'ada@example.com',
  role: 'mentor',
});
// → { userId, cohortMemberId, previousRole, role, rosterChanges: {
//       removedFromTeams, addedToTeams, removedStaffFrom, addedStaffTo } }

// Shallow: removes them from the cohort and its teams. Their account and org
// membership survive — they may belong to other cohorts.
await projex.cohorts.members.remove(cohortId, { email: 'ada@example.com' });
// → { ok: true, userId, role }

const { data, nextCursor } = await projex.teams.list(cohortId);
// → data: [{ id, publicId, name, description, cohortId, teamKind,
//            memberCount, staffCount }]

// Paged like every list method — 50 per page, 100 max. Filters on top of
// { q, limit, cursor }: teamKind ('multi' | 'solo') and memberEmail.
await projex.teams.list(cohortId, { q: 'rocket', teamKind: 'multi' });

// Or let the SDK walk the pages — an individual cohort has one solo team
// per learner, so this is usually what you want.
for await (const team of projex.teams.iterate(cohortId)) {
  console.log(team.name);
}

await projex.teams.create(cohortId, {
  name: 'Team Rocket',
  description: 'Optional',
  coverImage: null,
});

await projex.teams.update(teamId, { name: 'Team Rocket II' });
// Also accepts: description, overview, coverImage.

// Soft-deletes the team and its tasks, submissions, members and staff. Its
// learners stay enrolled in the cohort but end up on no team.
await projex.teams.delete(teamId, { dryRun: true });
// → { dryRun: true, impact: { learners: 3, staff: 1 } }

await projex.teams.members.add(teamId, {
  email: 'ada@example.com',
  role: 'learner' | 'mentor' | 'evaluator',  // default: learner
  name: 'Ada Lovelace',
  notify: true,
});
// → the same ProvisioningSummary as cohorts.members.add

await projex.teams.members.changeRole(teamId, {
  email: 'ada@example.com',
  role: 'mentor',
});
// → { userId, teamId, teamRole }

// Removes whichever seat they hold. Cohort enrolment is untouched.
await projex.teams.members.remove(teamId, { email: 'ada@example.com' });
// → { ok: true, userId, removed: 'learner' | 'staff' }

import { ProjexApiError } from '@pkg-projex/sdk';

try {
  await projex.milestones.submit(ref, input);
} catch (err) {
  if (err instanceof ProjexApiError) {
    if (err.code === 'ambiguous_team') {
      // Prompt for teamId from cohorts.get(...).teams
    }
    console.error(err.status, err.code, err.message, err.requestId);
  }
  throw err;
}