@joymerrevent/porters-connect 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,684 @@
+/** Options for {@link TokenProvider.getAccessToken}. */
+type GetAccessTokenOptions = {
+    /** Force a refresh even if the cached token looks valid (reactive 401/402). */
+    forceRefresh?: boolean;
+};
+/** Supplies a valid Access Token, refreshing transparently when expired. */
+type TokenProvider = {
+    getAccessToken(opts?: GetAccessTokenOptions): Promise<string>;
+};
+/** Tokens persisted by a {@link TokenStore} (expiry is absolute epoch ms). */
+type StoredTokens = {
+    accessToken: string;
+    refreshToken: string;
+    accessTokenExpiresAt: number;
+    refreshTokenExpiresAt: number;
+};
+/**
+ * Pluggable token persistence (default: in-memory). Async so it can back onto
+ * redis / DB / file for multi-instance server use.
+ */
+type TokenStore = {
+    get(): Promise<StoredTokens | undefined>;
+    set(tokens: StoredTokens): Promise<void>;
+    clear(): Promise<void>;
+};
+
+/** A single HTTP request issued to the PORTERS API. */
+type TransportRequest = {
+    method: "GET" | "POST";
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+};
+/** The raw HTTP response. Body stays as text; XML parsing happens in `xml/`. */
+type TransportResponse = {
+    status: number;
+    body: string;
+};
+/** Sends a request and resolves the raw response. */
+type Transport = {
+    send(request: TransportRequest): Promise<TransportResponse>;
+};
+
+/** A mock reply: an XML body string (HTTP 200), or an explicit status + body. */
+type MockReply = string | {
+    status?: number;
+    body: string;
+};
+/**
+ * Maps a request to a {@link MockReply}, or returns `undefined` for "not mocked". When `undefined`
+ * is returned (and the request is not an auto-answered auth endpoint), the transport throws a
+ * {@link PortersConfigError} naming the request, so an unmocked route surfaces instead of silently
+ * returning an empty response.
+ */
+type MockHandler = (request: TransportRequest) => MockReply | undefined;
+/** Options for {@link createMockTransport}. */
+type MockTransportOptions = {
+    /**
+     * Auto-answer the OAuth `code_direct` (`/v1/oauth`) and token (`/v1/token`) endpoints with valid
+     * demo tokens, so callers only mock resource XML. Default `true`. Set `false` to handle the auth
+     * endpoints in your own handler.
+     */
+    auth?: boolean;
+};
+/**
+ * Build a {@link Transport} that answers from a handler instead of the network — run the library
+ * fully offline, with no PORTERS contract (R-17). Pass it as `new PortersClient({ transport })`.
+ *
+ * @example
+ * const transport = createMockTransport((req) =>
+ *   req.url.includes("/v1/candidate")
+ *     ? `<Candidate Total="0" Count="0" Start="0"><Code>0</Code></Candidate>`
+ *     : undefined, // unmocked -> a clear PortersConfigError
+ * );
+ */
+declare const createMockTransport: (handler: MockHandler, options?: MockTransportOptions) => Transport;
+
+type DataType = "System[Id]" | "Number" | "DateTime" | "System[DateTime]" | "Date" | "Age" | "SinglelineText" | "MultilineText" | "Mail" | "Telephone" | "URL" | "User" | "Option" | "System[Reference]";
+/** A referenced User (Read is nested; Write is `User.P_Id` only). */
+type UserRef = {
+    P_Id: number | null;
+    P_Type: string | null;
+    P_Name: string | null;
+    P_Mail: string | null;
+};
+type FieldValue = string | number | string[] | UserRef | null;
+type DecodedValue<D extends DataType> = D extends "System[Id]" | "Number" | "System[Reference]" ? number : D extends "User" ? UserRef : D extends "Option" ? string[] : string;
+
+type WritableDataType = Exclude<DataType, "System[Id]" | "System[DateTime]">;
+type WriteValueOf<D extends DataType> = D extends "User" | "System[Reference]" | "Number" ? number : D extends "Option" ? string[] : string;
+
+type FieldCatalog = Record<string, DataType>;
+/**
+ * "No custom fields": the intersection-identity default for the generic catalog params (ADR-0023).
+ * A bare `{}` is flagged by `no-empty-object-type`; `Record<never, never>` is the same empty object,
+ * lint-clean, adds no keys in `static & C`, and satisfies both `FieldCatalog` and `DeclaredCatalogs`.
+ * Lives here (with `FieldCatalog`) so resources need not import from the higher-level `fields/` (RV-8).
+ */
+type EmptyCatalog = Record<never, never>;
+/**
+ * A decoded record: every known field, each `DecodedValue | null`, and **optional** because a
+ * field not named in `field` is simply absent (SD-3 "simple" type — ADR-0005/0019). Custom
+ * `U_`/`A_` aliases are not in the catalog, so they are not typed here (access via a cast until
+ * the declaration DSL lands — ADR-0005 SD-2); at runtime they still pass through as raw values.
+ */
+type ReadRecord<F extends FieldCatalog> = {
+    [K in keyof F]?: DecodedValue<F[K]> | null;
+};
+type ResourcePage<F extends FieldCatalog> = {
+    items: ReadRecord<F>[];
+    total: number;
+    count: number;
+    start: number;
+};
+
+type SearchQuery = {
+    /**
+     * Output fields as prefixed aliases (e.g. `Person.P_Name`). **Omit** to fetch every catalogued
+     * field by default (ADR-0020): PORTERS returns only the primary key for a fieldless request, so
+     * the library sends a catalog-derived default field set instead. Pass `[]` to opt into that
+     * API-native "primary key only" response (e.g. counting). A non-empty list is sent verbatim.
+     */
+    field?: string[];
+    condition?: Record<string, string>;
+    count?: number;
+    start?: number;
+};
+type WritableKeys<F extends FieldCatalog> = {
+    [K in keyof F]: F[K] extends WritableDataType ? K : never;
+}[keyof F];
+/**
+ * Create input (ADR-0019 W2): the `requiredOnCreate` aliases are **required** (non-null); every
+ * other writable field is optional (`null` omits). `P_Id` is supplied by the library — not here.
+ */
+type CreateInput<F extends FieldCatalog, Req extends keyof F> = {
+    [K in Req]: WriteValueOf<F[K]>;
+} & {
+    [K in Exclude<WritableKeys<F>, Req>]?: WriteValueOf<F[K]> | null;
+};
+/** Update input (ADR-0019 W2): every writable field optional (`null` omits, `""` clears). */
+type UpdateInput<F extends FieldCatalog> = {
+    [K in WritableKeys<F>]?: WriteValueOf<F[K]> | null;
+};
+type Resource<F extends FieldCatalog, Req extends keyof F> = {
+    search(query?: SearchQuery): Promise<ResourcePage<F>>;
+    /** Auto-paginating search: yields every matching record (200 per page). */
+    searchAll(query?: Omit<SearchQuery, "count" | "start">): AsyncIterable<ReadRecord<F>>;
+    get(id: number): Promise<ReadRecord<F> | undefined>;
+    /** Create one record; resolves to the newly assigned id. */
+    create(input: CreateInput<F, Req>): Promise<number>;
+    /** Update one record by id; resolves to that id. */
+    update(id: number, input: UpdateInput<F>): Promise<number>;
+};
+
+declare const FIELDS$8: {
+    readonly P_Id: "System[Id]";
+    readonly P_Owner: "User";
+    readonly P_RegistrationDate: "System[DateTime]";
+    readonly P_RegisteredBy: "User";
+    readonly P_UpdateDate: "System[DateTime]";
+    readonly P_UpdatedBy: "User";
+    readonly P_Phase: "Option";
+    readonly P_PhaseDate: "DateTime";
+    readonly P_Name: "SinglelineText";
+    readonly P_Reading: "SinglelineText";
+    readonly P_Mail: "Mail";
+    readonly P_MobileMail: "Mail";
+    readonly P_Telephone: "Telephone";
+    readonly P_Mobile: "Telephone";
+    readonly P_Country: "SinglelineText";
+    readonly P_Prefecture: "SinglelineText";
+    readonly P_City: "SinglelineText";
+    readonly P_Zipcode: "SinglelineText";
+};
+declare const REQUIRED_ON_CREATE$4: readonly ["P_Owner"];
+/** A decoded Candidate: known `P_` fields, each requested field `value | null`. */
+type Candidate = ReadRecord<typeof FIELDS$8>;
+type CandidatePage = ResourcePage<typeof FIELDS$8>;
+type CandidateSearchQuery = SearchQuery;
+/** Fields for `create`: `P_Owner` is required; `P_Id` / system timestamps are not settable. */
+type CandidateCreateInput = CreateInput<typeof FIELDS$8, (typeof REQUIRED_ON_CREATE$4)[number]>;
+/** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
+type CandidateUpdateInput = UpdateInput<typeof FIELDS$8>;
+/** The Candidate accessor; `C` is the declared custom-field catalog merged on (ADR-0023). */
+type CandidateResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$8 & C, (typeof REQUIRED_ON_CREATE$4)[number]>;
+
+declare const FIELDS$7: {
+    readonly P_Id: "System[Id]";
+    readonly P_Owner: "User";
+    readonly P_Client: "System[Reference]";
+    readonly P_Recruiter: "System[Reference]";
+    readonly P_RegistrationDate: "System[DateTime]";
+    readonly P_RegisteredBy: "User";
+    readonly P_UpdateDate: "System[DateTime]";
+    readonly P_UpdatedBy: "User";
+    readonly P_Phase: "Option";
+    readonly P_PhaseDate: "DateTime";
+    readonly P_PhaseMemo: "MultilineText";
+    readonly P_Position: "SinglelineText";
+    readonly P_Publish: "Option";
+    readonly P_JobCategorySummary: "MultilineText";
+    readonly P_JobCategory: "Option";
+    readonly P_IndustrySummary: "MultilineText";
+    readonly P_Industry: "Option";
+    readonly P_SalarySummary: "MultilineText";
+    readonly P_MinSalary: "Number";
+    readonly P_MaxSalary: "Number";
+    readonly P_AreaSummary: "MultilineText";
+    readonly P_Area: "Option";
+    readonly P_PayrollsText: "SinglelineText";
+    readonly P_Memo: "MultilineText";
+    readonly P_EmploymentPeriod: "MultilineText";
+    readonly P_WokingHours: "MultilineText";
+    readonly P_Holidays: "MultilineText";
+    readonly P_Benefits: "MultilineText";
+    readonly P_PubliclyTraded: "Option";
+    readonly P_SalesAmountText: "SinglelineText";
+    readonly P_EstablishmentDateText: "SinglelineText";
+    readonly P_CapitalText: "SinglelineText";
+    readonly P_EmploymentType: "Option";
+    readonly P_ExpectedAgeReason: "Option";
+};
+declare const REQUIRED_ON_CREATE$3: readonly ["P_Owner", "P_Client", "P_Recruiter"];
+/** A decoded Job: known `P_` fields, each requested field `value | null`. */
+type Job = ReadRecord<typeof FIELDS$7>;
+type JobPage = ResourcePage<typeof FIELDS$7>;
+type JobSearchQuery = SearchQuery;
+/** Fields for `create`: `P_Owner` required; `P_Id` / system timestamps are not settable. */
+type JobCreateInput = CreateInput<typeof FIELDS$7, (typeof REQUIRED_ON_CREATE$3)[number]>;
+/** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
+type JobUpdateInput = UpdateInput<typeof FIELDS$7>;
+/** The Job accessor; `C` is the declared custom-field catalog merged on (ADR-0023). */
+type JobResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$7 & C, (typeof REQUIRED_ON_CREATE$3)[number]>;
+
+declare const FIELDS$6: {
+    readonly P_Id: "System[Id]";
+    readonly P_Owner: "User";
+    readonly P_RegistrationDate: "System[DateTime]";
+    readonly P_RegisteredBy: "User";
+    readonly P_UpdateDate: "System[DateTime]";
+    readonly P_UpdatedBy: "User";
+    readonly P_Phase: "Option";
+    readonly P_PhaseDate: "DateTime";
+    readonly P_PhaseMemo: "MultilineText";
+    readonly P_Name: "SinglelineText";
+    readonly P_Memo: "MultilineText";
+    readonly P_Country: "SinglelineText";
+    readonly P_Prefecture: "SinglelineText";
+    readonly P_City: "SinglelineText";
+    readonly P_Street: "MultilineText";
+    readonly P_Zipcode: "SinglelineText";
+    readonly P_Telephone: "Telephone";
+    readonly P_Fax: "Telephone";
+};
+declare const REQUIRED_ON_CREATE$2: readonly ["P_Owner"];
+/** A decoded Client (company): known `P_` fields, each requested field `value | null`. */
+type Client = ReadRecord<typeof FIELDS$6>;
+type ClientPage = ResourcePage<typeof FIELDS$6>;
+type ClientSearchQuery = SearchQuery;
+/** Fields for `create`: `P_Owner` required; `P_Id` / system timestamps are not settable. */
+type ClientCreateInput = CreateInput<typeof FIELDS$6, (typeof REQUIRED_ON_CREATE$2)[number]>;
+/** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
+type ClientUpdateInput = UpdateInput<typeof FIELDS$6>;
+/** The Client accessor; `C` is the declared custom-field catalog merged on (ADR-0023). */
+type ClientResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$6 & C, (typeof REQUIRED_ON_CREATE$2)[number]>;
+
+declare const FIELDS$5: {
+    readonly P_Id: "System[Id]";
+    readonly P_Owner: "User";
+    readonly P_Client: "System[Reference]";
+    readonly P_Recruiter: "System[Reference]";
+    readonly P_Job: "System[Reference]";
+    readonly P_Candidate: "System[Reference]";
+    readonly P_Resume: "System[Reference]";
+    readonly P_RegistrationDate: "System[DateTime]";
+    readonly P_RegisteredBy: "User";
+    readonly P_UpdateDate: "System[DateTime]";
+    readonly P_UpdatedBy: "User";
+    readonly P_Phase: "Option";
+    readonly P_PhaseDate: "DateTime";
+    readonly P_PhaseMemo: "MultilineText";
+    readonly P_Close: "Option";
+    readonly P_CloseReason: "Option";
+    readonly P_ExpectedSalesAmount: "Number";
+    readonly P_ExpectedClosingDate: "Date";
+};
+declare const REQUIRED_ON_CREATE$1: readonly ["P_Owner", "P_Client", "P_Recruiter", "P_Job", "P_Candidate", "P_Resume"];
+/** A decoded Process (a Candidate's progress through a Job): known `P_` fields, each
+ *  requested field `value | null`. */
+type Process = ReadRecord<typeof FIELDS$5>;
+type ProcessPage = ResourcePage<typeof FIELDS$5>;
+type ProcessSearchQuery = SearchQuery;
+/** Fields for `create`: `P_Owner` required; `P_Id` / system timestamps are not settable. */
+type ProcessCreateInput = CreateInput<typeof FIELDS$5, (typeof REQUIRED_ON_CREATE$1)[number]>;
+/** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
+type ProcessUpdateInput = UpdateInput<typeof FIELDS$5>;
+/** The Process accessor; `C` is the declared custom-field catalog merged on (ADR-0023). */
+type ProcessResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$5 & C, (typeof REQUIRED_ON_CREATE$1)[number]>;
+
+declare const FIELDS$4: {
+    readonly P_Id: "System[Id]";
+    readonly P_Owner: "User";
+    readonly P_Candidate: "System[Reference]";
+    readonly P_RegistrationDate: "System[DateTime]";
+    readonly P_RegisteredBy: "User";
+    readonly P_UpdateDate: "System[DateTime]";
+    readonly P_UpdatedBy: "User";
+    readonly P_Phase: "Option";
+    readonly P_PhaseDate: "DateTime";
+    readonly P_PhaseMemo: "MultilineText";
+    readonly P_Name: "SinglelineText";
+    readonly P_RegisterChannel: "Option";
+    readonly P_Memo: "MultilineText";
+    readonly P_CurrentStatus: "Option";
+    readonly P_Education: "MultilineText";
+    readonly P_CarrierSummary: "MultilineText";
+    readonly P_CurrentSalary: "Number";
+    readonly P_ExperiencedJobCategory: "Option";
+    readonly P_ExperiencedIndustry: "Option";
+    readonly P_ChangeJobsCount: "Number";
+    readonly P_Gender: "Option";
+    readonly P_DateOfBirth: "Age";
+    readonly P_ExpectEmploymentType: "Option";
+    readonly P_ExpectArea: "Option";
+    readonly P_ExpectJobCategory: "Option";
+    readonly P_ExpectIndustry: "Option";
+    readonly P_ExpectCondition: "MultilineText";
+    readonly P_ExpectSalary: "Number";
+    readonly P_DesiredHourlyRate: "Number";
+    readonly P_HourlyRate: "Number";
+};
+declare const REQUIRED_ON_CREATE: readonly ["P_Owner", "P_Candidate"];
+/** A decoded Resume (a Candidate's CV / profile): known `P_` fields, each requested field
+ *  `value | null`. */
+type Resume = ReadRecord<typeof FIELDS$4>;
+type ResumePage = ResourcePage<typeof FIELDS$4>;
+type ResumeSearchQuery = SearchQuery;
+/** Fields for `create`: `P_Owner` required; `P_Id` / system timestamps are not settable. */
+type ResumeCreateInput = CreateInput<typeof FIELDS$4, (typeof REQUIRED_ON_CREATE)[number]>;
+/** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
+type ResumeUpdateInput = UpdateInput<typeof FIELDS$4>;
+/** The Resume accessor; `C` is the declared custom-field catalog merged on (ADR-0023). */
+type ResumeResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$4 & C, (typeof REQUIRED_ON_CREATE)[number]>;
+
+/** A decoded Attachment. A field is `null` unless it was returned (see `field`). */
+type Attachment = {
+    id: number | null;
+    /** Related resource type code (see the PORTERS Resource List). */
+    resource: number | null;
+    /** Related record id. */
+    resourceId: number | null;
+    contentType: string | null;
+    fileName: string | null;
+    /** Base64 file body. */
+    content: string | null;
+};
+type AttachmentPage = {
+    items: Attachment[];
+    total: number;
+    count: number;
+    start: number;
+};
+type AttachmentSearchQuery = {
+    /**
+     * Output fields. **Omit** to fetch metadata by default (Id / Resource / ResourceId /
+     * ContentType / FileName) — the large Base64 `Content` is excluded so listing doesn't download
+     * every file body (ADR-0020); request `["Content", …]` or use `get()` for the body. Pass `[]`
+     * for the API-native primary-key-only response. A non-empty list is sent verbatim.
+     */
+    field?: string[];
+    condition?: Record<string, string>;
+    count?: number;
+    start?: number;
+};
+/** Fields for creating an Attachment. `content` is the Base64 file body. */
+type AttachmentCreate = {
+    resource: number;
+    resourceId: number;
+    contentType: string;
+    fileName: string;
+    content: string;
+};
+/** Fields for updating an Attachment. `Resource` / `ResourceId` are not updatable. */
+type AttachmentUpdate = {
+    contentType?: string;
+    fileName?: string;
+    content?: string;
+};
+type AttachmentResource = {
+    search(query?: AttachmentSearchQuery): Promise<AttachmentPage>;
+    get(id: number): Promise<Attachment | undefined>;
+    /** Create an Attachment; resolves to the newly assigned id. */
+    create(input: AttachmentCreate): Promise<number>;
+    /** Update an Attachment by id; resolves to that id. */
+    update(id: number, input: AttachmentUpdate): Promise<number>;
+};
+
+declare const FIELDS$3: {
+    readonly P_Id: "System[Id]";
+    readonly P_Name: "SinglelineText";
+    readonly P_CompanyId: "SinglelineText";
+};
+/** A decoded Partition (a PORTERS contract company / Company DB). */
+type Partition = ReadRecord<typeof FIELDS$3>;
+type PartitionPage = ResourcePage<typeof FIELDS$3>;
+/** Partition Read query. `requestType` 1 = partitions this App can access (default). */
+type PartitionSearchQuery = {
+    /** 1 = accessible partitions (default). 0 = login partition (browser `code` grant only). */
+    requestType?: 0 | 1;
+    count?: number;
+    start?: number;
+};
+type PartitionResource = {
+    search(query?: PartitionSearchQuery): Promise<PartitionPage>;
+    /** Auto-paginating search: yields every accessible partition. */
+    searchAll(query?: Omit<PartitionSearchQuery, "count" | "start">): AsyncIterable<Partition>;
+};
+
+declare const FIELDS$2: {
+    readonly P_Id: "System[Id]";
+    readonly P_Type: "Number";
+    readonly P_Name: "SinglelineText";
+    readonly P_Mail: "Mail";
+};
+/** A decoded User (PORTERS operator). `P_Type`: 0 = standard user, 1 = system admin. */
+type User = ReadRecord<typeof FIELDS$2>;
+type UserPage = ResourcePage<typeof FIELDS$2>;
+/** User Read query. `requestType` 1 = all users (default); `userType` -1 = any (default). */
+type UserSearchQuery = {
+    /** 1 = all users (default). 0 = the current user (code_direct → the App's own user). */
+    requestType?: 0 | 1;
+    /** -1 = any (default), 0 = system admins, 1 = standard users. */
+    userType?: -1 | 0 | 1;
+    /** Output fields (prefixed aliases). Omit to get the 4 core fields (this catalog). */
+    field?: string[];
+    count?: number;
+    start?: number;
+};
+type UserResource = {
+    search(query?: UserSearchQuery): Promise<UserPage>;
+    /** Auto-paginating search: yields every matching user. */
+    searchAll(query?: Omit<UserSearchQuery, "count" | "start">): AsyncIterable<User>;
+    /**
+     * The current API user (`request_type=0`). Under the library's default `code_direct` auth
+     * this resolves to the App's own user (username = app name) — useful for self-identification.
+     * Under the browser `code` grant it is the logged-in user. Resolves `undefined` if none.
+     */
+    current(): Promise<User | undefined>;
+};
+
+declare const RESOURCE_VALUE: {
+    readonly candidate: 1;
+    readonly job: 3;
+    readonly client: 5;
+    readonly recruiter: 9;
+    readonly sales: 11;
+    readonly contract: 13;
+    readonly resume: 17;
+    readonly activity: 19;
+    readonly opportunity: 25;
+    readonly contact: 27;
+};
+/** A resource whose field catalog can be read (Field Read `resource` selector). */
+type ResourceType = keyof typeof RESOURCE_VALUE;
+declare const FIELDS$1: {
+    readonly P_Id: "System[Id]";
+    readonly P_Name: "SinglelineText";
+    readonly P_Alias: "SinglelineText";
+    readonly P_Type: "Number";
+    readonly P_Required: "Number";
+    readonly P_Max: "Number";
+    readonly P_Min: "Number";
+    readonly P_DecimalFraction: "Number";
+    readonly P_ReferTo: "Option";
+    readonly P_ResourceType: "Number";
+};
+/** A decoded Field definition. `P_Required`: 0 = normal, 1 = required. */
+type Field = ReadRecord<typeof FIELDS$1>;
+type FieldPage = ResourcePage<typeof FIELDS$1>;
+/** Field Read query. `resource` selects which resource's fields to read (required). */
+type FieldSearchQuery = {
+    resource: ResourceType;
+    /** -1 = all (default), 0 = unused only, 1 = in-use only. */
+    active?: -1 | 0 | 1;
+    count?: number;
+    start?: number;
+};
+type FieldResource = {
+    search(query: FieldSearchQuery): Promise<FieldPage>;
+    /** Auto-paginating search: yields every field of the resource. */
+    searchAll(query: Omit<FieldSearchQuery, "count" | "start">): AsyncIterable<Field>;
+};
+
+declare const FIELDS: {
+    readonly P_Id: "System[Id]";
+    readonly P_Name: "SinglelineText";
+    readonly P_Alias: "SinglelineText";
+    readonly P_ParentId: "Number";
+    readonly P_Type: "Number";
+    readonly P_Order: "Number";
+};
+/** A decoded Option (one choice). `P_ParentId` links to the parent; `P_Type` 0 = normal, 1–11 = a phase kind. */
+type Option = ReadRecord<typeof FIELDS>;
+/** Option Read query. `alias` selects a subtree root; `level` its depth (-1 all). */
+type OptionSearchQuery = {
+    /** Root alias of the subtree to read (e.g. `Option.P_Gender`). Omit for all. */
+    alias?: string;
+    /** Depth: -1 all (default), 0 = siblings of `alias`, 1+ = descendants. */
+    level?: number;
+    /** -1 = all (default), 0 = unused only, 1 = in-use only. */
+    enabled?: -1 | 0 | 1;
+    count?: number;
+};
+type OptionResource = {
+    /** Read options, flattened depth-first (all nodes; tree is reconstructable via `P_ParentId`). */
+    search(query?: OptionSearchQuery): Promise<Option[]>;
+};
+
+/** One custom field's declared Data Type — the builder's return value (ADR-0023 D2). */
+type FieldDef<D extends DataType> = {
+    readonly dataType: D;
+};
+type CustomDataType = "Number" | "SinglelineText" | "MultilineText" | "Mail" | "Telephone" | "URL" | "Date" | "DateTime" | "Age" | "Option" | "User";
+/** Builder passed to each resource declaration: one method per declarable Data Type. */
+type FieldBuilder = {
+    number(): FieldDef<"Number">;
+    singlelineText(): FieldDef<"SinglelineText">;
+    multilineText(): FieldDef<"MultilineText">;
+    mail(): FieldDef<"Mail">;
+    telephone(): FieldDef<"Telephone">;
+    url(): FieldDef<"URL">;
+    date(): FieldDef<"Date">;
+    dateTime(): FieldDef<"DateTime">;
+    age(): FieldDef<"Age">;
+    option(): FieldDef<"Option">;
+    user(): FieldDef<"User">;
+};
+/** Data resources that accept custom fields (ADR-0023 D6). Master / Attachment are excluded. */
+type CustomFieldResource = "candidate" | "job" | "client" | "process" | "resume";
+/** One resource's custom field declarations: alias -> {@link FieldDef}. */
+type ResourceDecl = Record<string, FieldDef<DataType>>;
+/** Declaration input: per (data) resource, a builder fn returning its custom fields. */
+type FieldDecls = {
+    [R in CustomFieldResource]?: (f: FieldBuilder) => ResourceDecl;
+};
+/** A per-resource custom catalog (bare alias -> Data Type), as produced by {@link defineFields}. */
+type CustomCatalog = Record<string, DataType>;
+/** Map of (data) resource -> its custom catalog; the client merges these into the static catalogs. */
+type DeclaredCatalogs = {
+    [R in CustomFieldResource]?: CustomCatalog;
+};
+type CatalogOf<R extends ResourceDecl> = {
+    [K in keyof R]: R[K]["dataType"];
+};
+/** The validated, branded result of {@link defineFields}, keyed by the declared resources. */
+type DeclaredCatalogsOf<D extends FieldDecls> = {
+    [R in keyof D]: D[R] extends (f: FieldBuilder) => infer Out ? Out extends ResourceDecl ? CatalogOf<Out> : never : never;
+};
+declare const definedFieldsBrand: unique symbol;
+/** A validated set of custom field catalogs (branded — the client does not re-validate). */
+type DefinedFields<C extends DeclaredCatalogs = DeclaredCatalogs> = C & {
+    readonly [definedFieldsBrand]: true;
+};
+/** The custom catalog declared for resource `K` (or `{}` if none) — types each accessor (ADR-0023 D1). */
+type CustomFor<C extends DeclaredCatalogs, K extends CustomFieldResource> = K extends keyof C ? C[K] extends CustomCatalog ? C[K] : EmptyCatalog : EmptyCatalog;
+/**
+ * Declare tenant-specific custom fields per data resource (ADR-0023). This is the validation
+ * boundary: it throws {@link PortersConfigError} synchronously for an unknown resource key or an
+ * alias that is not `U_`/`A_`-prefixed. The branded result is passed to `PortersClient({ fields })`,
+ * which merges each catalog into the resource so the custom fields decode/encode by their declared
+ * Data Type and appear typed on reads / writes.
+ *
+ * @example
+ * const myFields = defineFields({
+ *   candidate: (f) => ({ U_score: f.number(), U_source: f.option() }),
+ * });
+ */
+declare const defineFields: <D extends FieldDecls>(decls: D) => DefinedFields<DeclaredCatalogsOf<D>>;
+
+/** OAuth scope string: `<resource>_r` (read) or `<resource>_w` (write). */
+type Scope = `${string}_r` | `${string}_w`;
+/** A PORTERS partition (Company DB) id. */
+type PartitionId = number;
+
+/** Options for constructing a {@link PortersClient}. `C` is inferred from `fields` (ADR-0023). */
+type PortersClientOptions<C extends DeclaredCatalogs = EmptyCatalog> = {
+    /**
+     * API host. Required and supplied via `PORTERS_HOST` — never hard-code it.
+     * (A representative value lives in docs/reference.)
+     */
+    host: string;
+    appId?: string;
+    appSecret?: string;
+    scopes?: Scope[];
+    /** Default partition; overridable per call (ADR-0008). */
+    partition?: PartitionId;
+    /** Custom auth strategy; defaults to the transparent code_direct strategy. */
+    auth?: TokenProvider;
+    /** Token persistence; defaults to in-memory. */
+    tokenStore?: TokenStore;
+    /** Injectable HTTP transport; defaults to a fetch-based transport. */
+    transport?: Transport;
+    /**
+     * Tenant custom field declarations from {@link defineFields} (ADR-0023). Each resource's
+     * declared `U_`/`A_` fields are merged onto its static catalog, so they decode/encode by
+     * their declared Data Type and appear typed on reads / writes. Omit for standard `P_` only.
+     */
+    fields?: DefinedFields<C>;
+};
+/**
+ * Entry point of the library. Wires the default transport / auth / throttle /
+ * requester and exposes namespaced resource accessors such as `candidate`
+ * (ADR-0005).
+ */
+declare class PortersClient<C extends DeclaredCatalogs = EmptyCatalog> {
+    #private;
+    readonly candidate: CandidateResource<CustomFor<C, "candidate">>;
+    readonly job: JobResource<CustomFor<C, "job">>;
+    readonly client: ClientResource<CustomFor<C, "client">>;
+    readonly process: ProcessResource<CustomFor<C, "process">>;
+    readonly resume: ResumeResource<CustomFor<C, "resume">>;
+    readonly attachment: AttachmentResource;
+    /** Master Read: accessible partitions (ADR-0021/0022). */
+    readonly partition: PartitionResource;
+    /** Master Read: users, plus `current()` self-identification (ADR-0021/0022). */
+    readonly user: UserResource;
+    /** Master Read: a resource's field catalog (ADR-0021/0022). */
+    readonly field: FieldResource;
+    /** Master Read: a tenant's choice (option) master (ADR-0021/0022). */
+    readonly option: OptionResource;
+    constructor(options: PortersClientOptions<C>);
+    /** The configured API host. */
+    get host(): string;
+}
+
+/** Cross-cutting classification shared by every PORTERS error. */
+type ErrorCategory = "auth" | "permission" | "validation" | "notFound" | "conflict" | "rateLimit" | "transient" | "network" | "server" | "config" | "unknown";
+/** Where the failing call was aimed (for self-service debugging). */
+type PortersErrorContext = {
+    resource?: string;
+    operation?: string;
+    partition?: number;
+};
+/** Construction options for {@link PortersError}. */
+type PortersErrorOptions = {
+    category: ErrorCategory;
+    /** PORTERS raw code; `null` for network/transport failures. */
+    code?: number | null;
+    retryable?: boolean;
+    /** Actionable hint (English by default). */
+    hint?: string;
+    httpStatus?: number;
+    context?: PortersErrorContext;
+    cause?: unknown;
+};
+/** Base class for every PORTERS-originated error (catch-all). */
+declare class PortersError extends Error {
+    readonly category: ErrorCategory;
+    readonly code: number | null;
+    readonly retryable: boolean;
+    readonly hint?: string;
+    readonly httpStatus?: number;
+    readonly context?: PortersErrorContext;
+    constructor(message: string, options: PortersErrorOptions);
+}
+/** OAuth / Token errors. */
+declare class PortersAuthError extends PortersError {
+}
+/** Resource API errors. */
+declare class PortersResourceError extends PortersError {
+}
+/** Connection / timeout / forced rate-limit disconnect. */
+declare class PortersNetworkError extends PortersError {
+}
+/** Misconfiguration / misuse — not PORTERS-originated; thrown synchronously. */
+declare class PortersConfigError extends PortersError {
+}
+
+/** Encode raw bytes to a Base64 string. */
+declare const bytesToBase64: (bytes: Uint8Array) => string;
+/** Decode a Base64 string back to raw bytes. */
+declare const base64ToBytes: (b64: string) => Uint8Array;
+
+export { type Attachment, type AttachmentCreate, type AttachmentPage, type AttachmentResource, type AttachmentSearchQuery, type AttachmentUpdate, type Candidate, type CandidateCreateInput, type CandidatePage, type CandidateResource, type CandidateSearchQuery, type CandidateUpdateInput, type Client, type ClientCreateInput, type ClientPage, type ClientResource, type ClientSearchQuery, type ClientUpdateInput, type CustomDataType, type DefinedFields, type ErrorCategory, type Field, type FieldBuilder, type FieldDecls, type FieldDef, type FieldPage, type FieldResource, type FieldSearchQuery, type FieldValue, type GetAccessTokenOptions, type Job, type JobCreateInput, type JobPage, type JobResource, type JobSearchQuery, type JobUpdateInput, type MockHandler, type MockReply, type MockTransportOptions, type Option, type OptionResource, type OptionSearchQuery, type Partition, type PartitionId, type PartitionPage, type PartitionResource, type PartitionSearchQuery, PortersAuthError, PortersClient, type PortersClientOptions, PortersConfigError, PortersError, type PortersErrorContext, type PortersErrorOptions, PortersNetworkError, PortersResourceError, type Process, type ProcessCreateInput, type ProcessPage, type ProcessResource, type ProcessSearchQuery, type ProcessUpdateInput, type ResourceType, type Resume, type ResumeCreateInput, type ResumePage, type ResumeResource, type ResumeSearchQuery, type ResumeUpdateInput, type Scope, type StoredTokens, type TokenProvider, type TokenStore, type Transport, type TransportRequest, type TransportResponse, type User, type UserPage, type UserRef, type UserResource, type UserSearchQuery, base64ToBytes, bytesToBase64, createMockTransport, defineFields };