@updraft-solutions/mcrit-sdk 0.4.0 → 0.5.0

package/src/schemas/training.ts

@@ -0,0 +1,500 @@
+import { z } from "zod";
+
+// ── Grading scales ──
+
+// No i18n in scale data — a plain German `key` + `description`, verbatim
+// from the source paper form (e.g. J3). The UI shows the key (chip/button),
+// the description as a tooltip. App-level i18n (our own UI labels) is
+// unaffected — only DATA i18n (per-point `{de,en,no}` labels) was removed.
+export const gradingScalePointSchema = z.object({
+  key: z.string(),
+  description: z.string(),
+});
+export type GradingScalePoint = z.infer<typeof gradingScalePointSchema>;
+
+export const gradingScaleSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  points: z.array(gradingScalePointSchema),
+});
+export type GradingScale = z.infer<typeof gradingScaleSchema>;
+
+export const GradingScaleFormSchema = z.object({
+  name: z.string().min(1).max(255),
+  points: z.array(gradingScalePointSchema).min(2),
+});
+export type GradingScaleForm = z.infer<typeof GradingScaleFormSchema>;
+
+// ── Training elements (catalog) ──
+
+export const TrainingElementKindEnum = z.enum([
+  "flight_exercise",
+  "theory",
+  "briefing",
+  "check",
+]);
+export type TrainingElementKind = z.infer<typeof TrainingElementKindEnum>;
+
+export const trainingElementSchema = z.object({
+  id: z.number(),
+  code: z.string(),
+  name: z.string(),
+  description: z.string().nullable().optional(),
+  kind: TrainingElementKindEnum,
+  grading_scale_id: z.number().nullable().optional(),
+  grading_scale: gradingScaleSchema.nullable(),
+  is_active: z.boolean(),
+  // Where-used count — how many of the company's syllabi carry this
+  // element (`TrainingElementController::index`'s `attached_syllabi_count`
+  // withCount alias). Absent on any payload that doesn't count it.
+  attached_syllabi_count: z.number().optional(),
+  // Provenance stamp (which template element this row was seeded/adopted
+  // from) — not yet exposed by TrainingElementResource; optional/forward-
+  // compatible.
+  template_element_id: z.number().nullable().optional(),
+});
+export type TrainingElement = z.infer<typeof trainingElementSchema>;
+
+export const TrainingElementFormSchema = z.object({
+  code: z.string().min(1).max(32),
+  name: z.string().min(1).max(255),
+  description: z.string().nullable().optional(),
+  kind: TrainingElementKindEnum,
+  grading_scale_id: z.number().nullable().optional(),
+  is_active: z.boolean().optional(),
+});
+export type TrainingElementForm = z.infer<typeof TrainingElementFormSchema>;
+
+// ── Syllabus (first-class, company-owned — see
+// docs/superpowers/specs/2026-08-03-syllabus-model-design.md) ──
+
+// A syllabus's kind (Amendment 3 — progress checks): `regular` drives the
+// Übersicht / per-flight Ausbildungsnachweis as before; `progress_check`
+// marks a check sheet (A41–A44 / D4 style) that is attached to courses via
+// `course_check_syllabi` and filled on demand per booking. `.default` keeps
+// pre-amendment fixtures/payloads parseable while the inferred output type
+// stays required.
+export const SyllabusKindEnum = z.enum(["regular", "progress_check"]);
+export type SyllabusKind = z.infer<typeof SyllabusKindEnum>;
+
+export const syllabusElementSchema = z.object({
+  id: z.number(),
+  syllabus_id: z.number(),
+  // Embedded so a row still renders once its element is deactivated;
+  // `.nullable().optional()` mirrors `trainingRecordEntrySchema`'s own
+  // embedded-element convention — the backend omits the key entirely on any
+  // response that didn't eager-load the relation.
+  training_element: trainingElementSchema.nullable().optional(),
+  // The sheet's section header (was `phase` pre-amendment). `null` = no
+  // group declared.
+  group: z.string().nullable().optional(),
+  sort_order: z.number(),
+  is_required_each_flight: z.boolean(),
+});
+export type SyllabusElement = z.infer<typeof syllabusElementSchema>;
+
+export const AttachSyllabusElementFormSchema = z.object({
+  training_element_id: z.number(),
+  group: z.string().nullable().optional(),
+  sort_order: z.number().int().min(0).optional(),
+  is_required_each_flight: z.boolean().optional(),
+});
+export type AttachSyllabusElementForm = z.infer<
+  typeof AttachSyllabusElementFormSchema
+>;
+
+export const UpdateSyllabusElementFormSchema = z.object({
+  group: z.string().nullable().optional(),
+  sort_order: z.number().int().min(0).optional(),
+  is_required_each_flight: z.boolean().optional(),
+});
+export type UpdateSyllabusElementForm = z.infer<
+  typeof UpdateSyllabusElementFormSchema
+>;
+
+// One row of the `POST syllabi/{syllabus}/elements/reorder` payload — the
+// full flat order AND the (frontend-computed, authoritative) `group` per
+// row in one pass. `group` is the corrected value after group-adoption-on-
+// drag (see `app/utils/syllabusGroupAdoption.ts`), not just the row's prior
+// value — a drag that moves a row into another group's block changes its
+// group, not only its position.
+export const ReorderSyllabusElementItemSchema = z.object({
+  id: z.number(),
+  group: z.string().nullable(),
+});
+export type ReorderSyllabusElementItem = z.infer<
+  typeof ReorderSyllabusElementItemSchema
+>;
+
+// One lean entry per distinct course referencing a syllabus via either
+// pointer or a `course_check_syllabi` attachment
+// (`SyllabusResource::buildUsedByCourses` — deduped, a course using both
+// pointers gets a single `as: "both"` entry, never two rows; `"check"` marks
+// a check-sheet attachment, which kind enforcement keeps disjoint from the
+// pointer tags — `"both"` stays pointer-only).
+export const usedByCourseSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  as: z.enum(["syllabus", "booking_form", "both", "check"]),
+});
+export type UsedByCourse = z.infer<typeof usedByCourseSchema>;
+
+export const syllabusSchema = z.object({
+  id: z.number(),
+  company_id: z.number(),
+  name: z.string(),
+  description: z.string().nullable().optional(),
+  // `regular` | `progress_check` — a CONTENT field like
+  // `has_flight_evaluation`: changing it on a published, in-use revision
+  // auto-spawns a draft.
+  kind: SyllabusKindEnum.default("regular"),
+  // Gates whether the per-flight record renders/validates section 2
+  // (Gesamtbewertung + the three "Anmerkungen des Fluglehrers" prompts).
+  has_flight_evaluation: z.boolean(),
+  // Gates whether `ready-to-sign` issues a student countersignature
+  // alongside the instructor's — per-syllabus (Amendment 2, replaces the
+  // former company-wide toggle).
+  requires_student_signature: z.boolean(),
+  // ── Versioning (Amendment 2) — always present, flat (no server-side
+  // lineage grouping; the frontend groups client-side from these fields). ──
+  version: z.number(),
+  root_syllabus_id: z.number().nullable(),
+  is_draft: z.boolean(),
+  // Derived server-side from the same eager-loaded where-used collections as
+  // the two `courses_as_*_count` fields below — same availability (`index`
+  // AND `show`, absent on `store`/`update`).
+  is_in_use: z.boolean().optional(),
+  // Transient, request-scoped: present (non-null) only on the response of a
+  // mutation that just auto-spawned THIS row as the new draft — never a
+  // persisted property. The frontend's signal to toast-explain and
+  // `router.replace` onto this syllabus's own page.
+  spawned_from_id: z.number().nullable().optional(),
+  // Only present when the relation was loaded (`show`/`store`/`update` —
+  // never on the `index` list).
+  elements: z.array(syllabusElementSchema).optional(),
+  // `withCount('elements')` — present on `index` AND `show`; absent on
+  // `store`/`update` responses (use `elements.length` there instead, since
+  // those always eager-load the full `elements` relation anyway).
+  elements_count: z.number().optional(),
+  // Where-used — present on `index` AND `show` (both eager-load both
+  // `coursesAs*` relations); absent on `store`/`update`.
+  courses_as_syllabus_count: z.number().optional(),
+  courses_as_booking_form_syllabus_count: z.number().optional(),
+  // One deduped entry per distinct course referencing this syllabus via
+  // either pointer (`as: "both"` when a course uses it for both). Same
+  // availability as the two counts above.
+  used_by_courses: z.array(usedByCourseSchema).optional(),
+  // Heavier metric, `show` only.
+  materialized_enrollment_count: z.number().optional(),
+  // Server-evaluated per-instance policy decisions (`HasGatesOnRequest`) —
+  // present when the fetch sends `permissions[syllabus]=*`. Loose record on
+  // purpose, same rationale as `companySchema.can`.
+  can: z.record(z.string(), z.boolean().nullable()).optional(),
+  created_at: z.string().optional(),
+  updated_at: z.string().optional(),
+});
+export type Syllabus = z.infer<typeof syllabusSchema>;
+
+export const StoreSyllabusFormSchema = z.object({
+  name: z.string().min(1).max(255),
+  description: z.string().nullable().optional(),
+  kind: SyllabusKindEnum.optional(),
+  has_flight_evaluation: z.boolean().optional(),
+  requires_student_signature: z.boolean().optional(),
+});
+export type StoreSyllabusForm = z.infer<typeof StoreSyllabusFormSchema>;
+
+export const UpdateSyllabusFormSchema = z.object({
+  name: z.string().min(1).max(255).optional(),
+  description: z.string().nullable().optional(),
+  kind: SyllabusKindEnum.optional(),
+  has_flight_evaluation: z.boolean().optional(),
+  requires_student_signature: z.boolean().optional(),
+});
+export type UpdateSyllabusForm = z.infer<typeof UpdateSyllabusFormSchema>;
+
+// The lean `{id, name, version, kind}` shape `CourseResource` /
+// `BaseCourseResource` serialize for each attached check syllabus
+// (`check_syllabi`, present on course show/update responses).
+export const courseCheckSyllabusSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  version: z.number(),
+  kind: SyllabusKindEnum.default("regular"),
+});
+export type CourseCheckSyllabus = z.infer<typeof courseCheckSyllabusSchema>;
+
+// A syllabus-element mutation endpoint's uniform response (attach/update/
+// detach/reorder all return this shape — never a bare 204 — precisely so a
+// spawn can be detected and the frontend can redirect in one round trip).
+export const syllabusElementMutationResultSchema = z.object({
+  syllabus: syllabusSchema,
+  element: syllabusElementSchema.nullable(),
+  spawned_from_id: z.number().nullable(),
+});
+export type SyllabusElementMutationResult = z.infer<
+  typeof syllabusElementMutationResultSchema
+>;
+
+// `POST syllabi/{syllabus}/rollout` response. `pointer: "check"` rows are
+// `course_check_syllabi` re-attachments (Amendment 3).
+export const syllabusRolloutResultItemSchema = z.object({
+  course_id: z.number(),
+  course_name: z.string(),
+  pointer: z.enum(["syllabus", "booking_form", "check"]),
+});
+// Attachments left on the older revision because the rolled-out revision's
+// kind doesn't fit that attachment type (`RolloutSyllabusRevision`'s kind
+// guard: pointers need regular, the check pivot needs progress_check) — the
+// rollout surface must report these, never silently drop them.
+export const syllabusRolloutSkippedItemSchema =
+  syllabusRolloutResultItemSchema.extend({
+    reason: z.enum(["kind_mismatch"]),
+  });
+export const syllabusRolloutResultSchema = z.object({
+  results: z.array(syllabusRolloutResultItemSchema),
+  skipped: z.array(syllabusRolloutSkippedItemSchema),
+});
+export type SyllabusRolloutResultItem = z.infer<
+  typeof syllabusRolloutResultItemSchema
+>;
+export type SyllabusRolloutSkippedItem = z.infer<
+  typeof syllabusRolloutSkippedItemSchema
+>;
+export type SyllabusRolloutResult = z.infer<typeof syllabusRolloutResultSchema>;
+
+// ── Enrollment training Übersicht ──
+
+export const EnrollmentTrainingStatusEnum = z.enum([
+  "not_started",
+  "in_training",
+  "completed",
+  "removed_from_syllabus",
+]);
+export type EnrollmentTrainingStatus = z.infer<
+  typeof EnrollmentTrainingStatusEnum
+>;
+
+export const gradeHistoryItemSchema = z.object({
+  training_record_id: z.number(),
+  booking_id: z.number(),
+  date: z.string().nullable().optional(),
+  grade_key: z.string().nullable().optional(),
+  comment: z.string().nullable().optional(),
+  instructor_name: z.string().nullable().optional(),
+});
+export type GradeHistoryItem = z.infer<typeof gradeHistoryItemSchema>;
+
+export const enrollmentTrainingElementSchema = z.object({
+  id: z.number(),
+  course_enrollment_id: z.number(),
+  status: EnrollmentTrainingStatusEnum,
+  // Denormalized from the course's (Übersicht-driving) syllabus row at
+  // materialization time — was `phase` pre-amendment.
+  group_label: z.string().nullable().optional(),
+  sort_order: z.number(),
+  signed_off_at: z.string().nullable(),
+  signed_off_by: z
+    .object({
+      id: z.number(),
+      name: z.string().optional(),
+    })
+    .nullable(),
+  notes: z.string().nullable().optional(),
+  training_element: trainingElementSchema,
+  grade_history: z.array(gradeHistoryItemSchema),
+  latest_grade_key: z.string().nullable().optional(),
+});
+export type EnrollmentTrainingElement = z.infer<
+  typeof enrollmentTrainingElementSchema
+>;
+
+export const SignOffTrainingElementFormSchema = z.object({
+  notes: z.string().nullable().optional(),
+  signed_off_by_membership_id: z.number().nullable().optional(),
+});
+export type SignOffTrainingElementForm = z.infer<
+  typeof SignOffTrainingElementFormSchema
+>;
+
+// ── Training records (per-flight) ──
+
+export const TrainingRecordStatusEnum = z.enum([
+  "draft",
+  "awaiting_signatures",
+  "signed",
+]);
+export type TrainingRecordStatus = z.infer<typeof TrainingRecordStatusEnum>;
+
+// The pass/fail "Ergebnis" of a progress check — only records stamped with a
+// check-kind sheet may carry it (backend 422s otherwise), and it is required
+// before ready-to-sign on those records.
+export const TrainingRecordResultEnum = z.enum(["passed", "failed"]);
+export type TrainingRecordResult = z.infer<typeof TrainingRecordResultEnum>;
+
+export const trainingRecordEntrySchema = z.object({
+  id: z.number(),
+  training_element_id: z.number(),
+  // Embedded so a signed record (immutable evidence) still renders fully
+  // even if the element is later detached from the syllabus —
+  // callers must prefer this over resolving `training_element_id` against
+  // the (mutable, current) syllabus. `.nullable().optional()`: the backend
+  // omits the key entirely (via `whenLoaded`) on any response that didn't
+  // eager-load the relation, and could resolve it to `null` in a genuinely
+  // orphaned edge case — both degrade to "treat as unresolved", not a
+  // parse failure.
+  training_element: trainingElementSchema.nullable().optional(),
+  grade_key: z.string().nullable().optional(),
+  comment: z.string().nullable().optional(),
+});
+export type TrainingRecordEntry = z.infer<typeof trainingRecordEntrySchema>;
+
+export const trainingRecordEntryInputSchema = z.object({
+  training_element_id: z.number(),
+  grade_key: z.string().nullable().optional(),
+  comment: z.string().nullable().optional(),
+});
+export type TrainingRecordEntryInput = z.infer<
+  typeof trainingRecordEntryInputSchema
+>;
+
+// Mirrors the generic `SignatureResource` (App\Http\Resources\Form) — the
+// same polymorphic `Signature` model backs both form submissions and
+// training records. Kept self-contained here (not imported from
+// @schemas/FormTemplateSchema) to match this file's own alias root and the
+// courseMilestone.ts convention of no cross-schema imports.
+export const trainingSignatureSchema = z.object({
+  type: z.literal("signature").optional(),
+  id: z.number(),
+  signable_type: z.string().optional(),
+  signable_id: z.number().optional(),
+  field_key: z.string(),
+  status: z.enum(["pending", "signed", "revoked"]),
+  required_signer_membership_id: z.number().nullable(),
+  required_signer_name: z.string().nullable().optional(),
+  required_signer_permission: z.string().nullable().optional(),
+  signed_by_user_id: z.number().nullable(),
+  signed_by_membership_id: z.number().nullable(),
+  signed_by_name: z.string().nullable().optional(),
+  is_current_user_designated: z.boolean().optional().default(false),
+  signed_at: z.string().nullable(),
+  image: z.string().nullable(),
+  data_hash: z.string().nullable(),
+  schema_version: z.number().nullable(),
+  schema_hash: z.string().nullable(),
+  consent_text_hash: z.string().nullable(),
+  auth_method: z.string().nullable(),
+  auth_verified_at: z.string().nullable(),
+  ip_address: z.string().nullable(),
+  user_agent: z.string().nullable(),
+  geo_country: z.string().nullable(),
+  signing_event_id: z.string().nullable(),
+  created_at: z.string().optional(),
+  updated_at: z.string().optional(),
+});
+export type TrainingSignature = z.infer<typeof trainingSignatureSchema>;
+
+export const trainingRecordSchema = z.object({
+  id: z.number(),
+  booking_id: z.number(),
+  course_enrollment_id: z.number(),
+  instructor_membership_id: z.number().nullable().optional(),
+  status: TrainingRecordStatusEnum,
+  // Whether section 2 (Gesamtbewertung + Anmerkungen) applies at all — read
+  // live off the course's booking-form syllabus by
+  // `TrainingRecordResource`, the single source of truth. `false` (never
+  // absent) when there's no booking-form syllabus at all.
+  has_flight_evaluation: z.boolean().default(false),
+  // The exact booking-form syllabus revision stamped at CREATE time (never
+  // on a later update) — the audit-chain provenance ("Rev. n this session
+  // was graded against"). `syllabus` is `null` when the course had no
+  // booking-form syllabus assigned at creation time.
+  syllabus_id: z.number().nullable().optional(),
+  // `kind` is the frontend's signal to render the check-only "Ergebnis"
+  // section for this record.
+  syllabus: z
+    .object({
+      id: z.number(),
+      name: z.string(),
+      version: z.number(),
+      kind: SyllabusKindEnum.default("regular"),
+    })
+    .nullable()
+    .optional(),
+  // Non-null only on check-kind records (see TrainingRecordResultEnum).
+  result: TrainingRecordResultEnum.nullable().optional(),
+  // The J3-mirroring fields — the Gesamtbewertung (a point key from the
+  // booking-form syllabus's element grading scales) plus the three
+  // "Anmerkungen des Fluglehrers" comment sections from the paper form.
+  overall_grade_key: z.string().nullable().optional(),
+  what_went_well: z.string().nullable().optional(),
+  needs_improvement: z.string().nullable().optional(),
+  repeat_next_flight: z.string().nullable().optional(),
+  entries: z.array(trainingRecordEntrySchema),
+  signatures: z.array(trainingSignatureSchema),
+  created_at: z.string().optional(),
+  updated_at: z.string().optional(),
+});
+export type TrainingRecord = z.infer<typeof trainingRecordSchema>;
+
+export const UpsertTrainingRecordFormSchema = z.object({
+  // CREATE only — which sheet this record fills (the course's booking-form
+  // syllabus when omitted, or one of its attached check syllabi). The choice
+  // IS the stamp; PATCH prohibits this key entirely (the stamp never moves).
+  syllabus_id: z.number().nullable().optional(),
+  // Check-kind sheets only — 422 on any other sheet.
+  result: TrainingRecordResultEnum.nullable().optional(),
+  overall_grade_key: z.string().nullable().optional(),
+  what_went_well: z.string().nullable().optional(),
+  needs_improvement: z.string().nullable().optional(),
+  repeat_next_flight: z.string().nullable().optional(),
+  instructor_membership_id: z.number().nullable().optional(),
+  entries: z.array(trainingRecordEntryInputSchema),
+});
+export type UpsertTrainingRecordForm = z.infer<
+  typeof UpsertTrainingRecordFormSchema
+>;
+
+// ── Training template packs (syllabus templates) ──
+
+export const trainingTemplatePackSchema = z.object({
+  key: z.string(),
+  name: z.string(),
+  description: z.string().nullable().optional(),
+  // Carried onto the syllabus the pack creates (regular vs. progress check).
+  kind: SyllabusKindEnum.default("regular"),
+  element_count: z.number().optional(),
+});
+export type TrainingTemplatePack = z.infer<typeof trainingTemplatePackSchema>;
+
+export const CreateSyllabusFromTemplateFormSchema = z.object({
+  template_key: z.string().min(1),
+});
+export type CreateSyllabusFromTemplateForm = z.infer<
+  typeof CreateSyllabusFromTemplateFormSchema
+>;
+
+// Mirrors `CreateSyllabusFromTemplate::run()`'s return shape (m-crit-api),
+// as wrapped by `SyllabusController::fromTemplate`.
+export const createSyllabusFromTemplateResultSchema = z.object({
+  catalog: z.object({
+    created: z.number(),
+    existing: z.number(),
+    adopted: z.number(),
+    mismatched: z.array(
+      z.object({
+        code: z.string(),
+        company_name: z.string(),
+        template_name: z.string(),
+      }),
+    ),
+  }),
+  elements: z.object({
+    created: z.number(),
+    existing: z.number(),
+  }),
+  syllabus: syllabusSchema,
+});
+export type CreateSyllabusFromTemplateResult = z.infer<
+  typeof createSyllabusFromTemplateResultSchema
+>;

package/src/types/ai.ts

@@ -0,0 +1,85 @@
+// AI assistant suggestion shapes. Suggestions are reviewable drafts — the
+// backend stores them as AiSuggestion rows; applying one only fills the local
+// edit form (or materializes through the subject model's normal endpoint).
+
+export type AiSuggestionStatus =
+  | "pending"
+  | "ready"
+  | "applied"
+  | "dismissed"
+  | "failed";
+
+export interface AiSuggestion<TPayload = unknown> {
+  type: "ai_suggestion";
+  id: number;
+  subject_type: string;
+  subject_id: number;
+  company_id: number | null;
+  suggestion_type: string;
+  locale: string;
+  payload: TPayload;
+  meta?: unknown;
+  status: AiSuggestionStatus;
+  requested_by: number | null;
+  applied_at: string | null;
+  dismissed_at: string | null;
+  created_at: string;
+}
+
+// Course description assistant.
+
+export interface AiSuggestedMilestone {
+  name: string;
+  description?: string | null;
+  kind: "progress" | "prerequisite" | "solo" | "cross_country";
+  is_prerequisite: boolean;
+  sort_order: number;
+}
+
+export interface CourseDescriptionSuggestionPayload {
+  title: string;
+  subtitle: string;
+  summary: string;
+  html: string;
+  milestones: AiSuggestedMilestone[];
+}
+
+// MIA logbook import (booking-scoped flight-log suggestions).
+
+export interface LogbookFlightLogPayload {
+  etdZ: string | null;
+  etaZ: string | null;
+  departure_airport_id: number | null;
+  destination_airport_id: number | null;
+  departure_airport_icao: string | null;
+  destination_airport_icao: string | null;
+  full_stop_landings: number;
+  touch_and_gos: number;
+  low_approaches: number;
+  crew_assignments: { membership_id: number; role: string }[];
+  membership_id: number | null;
+}
+
+export interface LogbookSuggestionMeta {
+  flags?: string[];
+  match?: { confidence: string; reasoning: string };
+  extraction?: { valid: boolean | null; discrepancy_minutes: number | null };
+  crew_text?: string | null;
+}
+
+export type LogbookSuggestion = AiSuggestion<LogbookFlightLogPayload> & {
+  meta?: LogbookSuggestionMeta;
+};
+
+export interface DiscardedRow {
+  reason: string;
+  flight: Record<string, unknown>;
+}
+
+export interface LogbookStageResult {
+  booking_id: number;
+  suggestion_ids: number[];
+  staged: number;
+  routed: Record<string, number> | number[];
+  discarded: DiscardedRow[];
+}

package/src/types/aircraft-block.ts

@@ -0,0 +1,23 @@
+export type AircraftBlockReason =
+  | "general"
+  | "ferry"
+  | "weather"
+  | "private"
+  | "aog"
+  | "other";
+
+export interface AircraftBlock {
+  type: "aircraftBlock";
+  id: number;
+  airplane_id: number;
+  company_id: number;
+  starts_at: string; // UTC ISO
+  ends_at: string; // UTC ISO
+  reason: AircraftBlockReason;
+  note: string | null;
+  is_maintenance: boolean;
+  maintenance_event_id: number | null;
+  created_at: string;
+  updated_at: string;
+  can?: Record<string, boolean | null>;
+}

package/src/types/api.ts

@@ -8,7 +8,9 @@ export interface DataWrappedResponse<T, M = undefined> {
   meta?: M;
 }
 
-export interface PaginatedResponse<T = any> {
+export type ApiResponse<T> = DataWrappedResponse<T>;
+
+export interface PaginatedResponse<T = unknown> {
   data: T[];
   meta: {
     current_page: number;

package/src/types/background-task.ts

@@ -0,0 +1,28 @@
+// Generic background-task tracking. A long-running server action returns a
+// BackgroundTask immediately (202); the client then tracks it to completion
+// via the Echo `background_task` signal (push) with a polling fallback.
+
+export type BackgroundTaskStatus =
+  | "queued"
+  | "processing"
+  | "completed"
+  | "failed"
+  | "canceled";
+
+export interface BackgroundTask<TResult = unknown> {
+  type: "background_task";
+  /** Store key — mirrors `uuid` (the API has no client-facing integer id). */
+  id: string;
+  uuid: string;
+  task_type: string;
+  status: BackgroundTaskStatus;
+  progress: number | null;
+  progress_label: string | null;
+  company_id: number | null;
+  user_id: number | null;
+  result: TResult | null;
+  error: string | null;
+  started_at: string | null;
+  finished_at: string | null;
+  created_at: string | null;
+}