@everfur/sdk 0.1.0

package/dist/records/index.d.cts

@@ -0,0 +1,224 @@
+import { f as EverfurError, E as EverfurResult } from '../EverfurResult-D92-uL82.cjs';
+export { g as EverfurErrorCategory, a as EverfurErrorCode } from '../EverfurResult-D92-uL82.cjs';
+import { P as PetRef, R as RecordsRequestId, D as DocumentId } from '../ids-CJ1S6adf.cjs';
+export { B as Brand, _ as __brand } from '../ids-CJ1S6adf.cjs';
+import { F as FileHandle } from '../FilePort-BabWrv7I.cjs';
+import { ReactNode } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+
+/**
+ * The partner-scoped projection of the backend records-request status (records_schemas.py). The internal
+ * `dispatching` / `parsing_failed` / `review_email_failed` values are already collapsed by the backend
+ * `from_db_status`; the clinic-dispatch statuses are out of partner scope (§0) and never appear here.
+ */
+type RecordsRequestStatus = 'awaiting_upload' | 'received' | 'parsing' | 'in_review' | 'published' | 'failed' | 'revoked';
+/** Terminal statuses: polling stops here. */
+declare const RECORDS_TERMINAL: readonly RecordsRequestStatus[];
+declare function isTerminalStatus(status: RecordsRequestStatus): boolean;
+interface RecordsRequestView {
+    readonly id: RecordsRequestId;
+    readonly petRef: PetRef;
+    readonly status: RecordsRequestStatus;
+    /** BE-authored copy, rendered verbatim (dumb-renderer rule). */
+    readonly statusLabel: string;
+    /**
+     * DEAD, measured 2026-08-22: no plane sends it and nothing in this SDK reads it. The widget
+     * `RecordsRequestResponse` omits it, the consumer `RecordsRequestSummary` has no such field either, and a
+     * grep of `src/` finds zero render consumers - so it is always the mapper's `0` default.
+     *
+     * Deliberately NOT deleted here: removing a non-optional public field is a breaking change that needs a
+     * major bump, which is a release decision. Documented so nobody reads a count off it.
+     */
+    readonly documentCount: number;
+    /** facts extracted but awaiting review (badge "N being reviewed"). */
+    readonly heldItemCount: number;
+    /** ISO; null before first upload. */
+    readonly receivedAt: string | null;
+    /** drives the timeline "reading your records" step. */
+    readonly parsingStartedAt: string | null;
+    /** non-null == a parse gap occurred (§5, honest, not silent). */
+    readonly reviewStartedAt: string | null;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+interface UploadedDocument {
+    readonly documentId: DocumentId;
+    readonly requestId: RecordsRequestId;
+    /** uploads NEVER auto-bind / auto-publish. */
+    readonly status: 'received';
+}
+/** One redacted identity row (name / species / breed / owner-safe field). Provenance absent. */
+interface RecordIdentityField {
+    readonly label: string;
+    readonly value: string;
+}
+/**
+ * Who produced a reading. `owner_reported` is owner-entered (a home scale, typed into the pet profile);
+ * `clinic_document` is extracted from a vet document. The two now share one series, so a clinician reading a
+ * weight can tell them apart before dosing from it.
+ *
+ * A value this build does not know folds to `null` (unlabelled), never to a guess - see `normalizeOrigin`.
+ * `null` therefore means "the backend did not say", NOT "clinic".
+ */
+type RecordOrigin = 'owner_reported' | 'clinic_document';
+/**
+ * One extracted clinical fact. No `raw_value` / `source_span` / `source_bbox` / `source_page` /
+ * `source_doc_id` / `value_source` / `extraction_method` / `source_precedence` members - `origin` is the only
+ * provenance-adjacent field, and it is a display label (see `RecordOrigin`).
+ */
+interface RecordEntity {
+    readonly key: string;
+    readonly category: string;
+    readonly label: string;
+    readonly value: string | null;
+    readonly unit: string | null;
+    readonly observedAt: string | null;
+    readonly status: string | null;
+    /** Who measured it. `null` when the backend did not label it (an older backend never does). */
+    readonly origin: RecordOrigin | null;
+}
+interface RecordSeriesPoint {
+    readonly at: string;
+    readonly value: number | null;
+    readonly display: string | null;
+    /** Who measured this reading. `null` when the backend did not label it - never assume `clinic_document`. */
+    readonly origin: RecordOrigin | null;
+}
+/** A time series of one entity (e.g. a weight trend). */
+interface RecordSeries {
+    readonly key: string;
+    readonly label: string;
+    readonly points: readonly RecordSeriesPoint[];
+}
+/** A forward-looking item (a due vaccine / follow-up). */
+interface RecordForwardItem {
+    readonly title: string;
+    readonly detail: string | null;
+    readonly dueAt: string | null;
+}
+/** Metadata for one source document, keyed by its id. No raw bytes / provenance. */
+interface RecordDocumentMeta {
+    readonly docId: string;
+    readonly title: string | null;
+    readonly pageCount: number | null;
+    readonly receivedAt: string | null;
+}
+/**
+ * The parsed record, ALREADY partner-redacted server-side (§5). `isEmpty` is the normal pre-parse render;
+ * `withheld` is the §5 fail-closed suppression (redaction could not be proven safe) and renders the WITHHELD
+ * state, never empty, never raw.
+ */
+interface RecordsView {
+    readonly petRef: PetRef;
+    readonly schemaVersion: string;
+    readonly isEmpty: boolean;
+    readonly withheld: boolean;
+    readonly generatedAt: string | null;
+    readonly identity: readonly RecordIdentityField[];
+    readonly entities: readonly RecordEntity[];
+    readonly entitySeries: readonly RecordSeries[];
+    readonly forwardLooking: readonly RecordForwardItem[];
+    readonly documents: Readonly<Record<string, RecordDocumentMeta>>;
+    /** BE-authored not-medical-advice notice, rendered verbatim. */
+    readonly disclaimer: string;
+}
+interface ConsentState {
+    readonly petRef: PetRef;
+    readonly granted: boolean;
+    /** consent-text version the user agreed to. */
+    readonly version: string | null;
+    readonly grantedAt: string | null;
+}
+interface CreateUploadRequestInput {
+    readonly petRef: PetRef;
+    /** /^[A-Za-z0-9._-]{8,128}$/ (§3.1). Idempotent: a replay returns the SAME request. */
+    readonly idempotencyKey: string;
+}
+interface GrantConsentInput {
+    readonly petRef: PetRef;
+    readonly consentVersion: string;
+    readonly idempotencyKey: string;
+}
+/**
+ * Why a records read/write was access-denied (all fold to `EverfurErrorCode = 'accessDenied'`, §7). The
+ * coarse reason selects the recovery affordance: `consent_required` -> consent CTA, `session_required` ->
+ * establish-session CTA, `entitlement` -> the CapabilityGate disabled surface.
+ */
+type RecordsDenialReason = 'consent_required' | 'session_required' | 'entitlement';
+/** Read the records denial reason off any settled error, defensively (null when absent). */
+declare function recordsDenialReasonOf(error: EverfurError | null): RecordsDenialReason | null;
+
+interface UploadDocumentInput {
+    readonly requestId: RecordsRequestId;
+    readonly file: FileHandle;
+    readonly onProgress?: (fraction: number) => void;
+    readonly signal?: AbortSignal;
+}
+interface RecordsController {
+    /** Create the self-upload request. Idempotent on `idempotencyKey`. Lands `awaiting_upload`. */
+    createUploadRequest(input: CreateUploadRequestInput): Promise<EverfurResult<RecordsRequestView>>;
+    /** Two-phase presigned upload of ONE document (§3.2). Bytes go DIRECT to S3. Resolves at `received`. */
+    uploadDocument(input: UploadDocumentInput): Promise<EverfurResult<UploadedDocument>>;
+    /** Poll one request's parse lifecycle. */
+    getRequest(id: RecordsRequestId): Promise<EverfurResult<RecordsRequestView>>;
+    /** All of this user's requests, newest-first (server-ordered). */
+    listRequests(): Promise<EverfurResult<readonly RecordsRequestView[]>>;
+    /** The parsed, partner-redacted record. Consent-gated + redaction-fail-closed. */
+    getRecord(pet: PetRef): Promise<EverfurResult<RecordsView>>;
+    /** Consent read-back. Never a hard failure for an absent row -> `granted:false`. */
+    getConsent(pet: PetRef): Promise<EverfurResult<ConsentState>>;
+    /** Grant content-exposure consent. Fail-closed audited server-side. Idempotent. */
+    grantConsent(input: GrantConsentInput): Promise<EverfurResult<ConsentState>>;
+    /** Revoke consent (prospective). Drops any cached record for the pet from memory. Idempotent. */
+    revokeConsent(pet: PetRef): Promise<EverfurResult<ConsentState>>;
+    /** The last record read for a pet, held in memory only; cleared on revoke. Null when none. */
+    peekCachedRecord(pet: PetRef): RecordsView | null;
+    /** Emit `records.capability.denied` (the rn CapabilityGate disabled surface calls this once, R12). */
+    reportCapabilityDenied(pet: PetRef | null): void;
+}
+
+type RecordsStatus = 'loading' | 'empty' | 'error' | 'populated';
+interface UseEverfurRecordsState {
+    readonly status: RecordsStatus;
+    readonly record: RecordsView | null;
+    readonly requests: readonly RecordsRequestView[];
+    /** the most-recent request, whose timeline the populated state renders. */
+    readonly activeRequest: RecordsRequestView | null;
+    readonly consent: ConsentState | null;
+    readonly error: EverfurError | null;
+    /** drives the recovery affordance: consent CTA / establish-session CTA / disabled. */
+    readonly denialReason: RecordsDenialReason | null;
+    /** §5.1 fail-closed suppression: render the withheld notice, never empty, never raw. */
+    readonly withheld: boolean;
+    readonly isUploading: boolean;
+    readonly uploadProgress: number | null;
+    /** Create a self-upload request the user attaches documents to. */
+    createRequest(idempotencyKey: string): Promise<EverfurResult<RecordsRequestView>>;
+    /** Two-phase presigned upload of one document to the active request. */
+    uploadDocument(requestId: RecordsRequestView['id'], file: FileHandle): Promise<EverfurResult<UploadedDocument>>;
+    /** Grant content-exposure consent, then fetch the record. */
+    grantConsent(consentVersion: string, idempotencyKey: string): Promise<EverfurResult<ConsentState>>;
+    /** Revoke consent (prospective); drops the record from view. */
+    revokeConsent(): Promise<EverfurResult<ConsentState>>;
+    /** Re-run the surface fetch (error retry). */
+    refresh(): void;
+}
+declare function useEverfurRecords(opts: {
+    readonly petRef: PetRef;
+    /** Host/test seam: inject a controller directly instead of acquiring one from the runtime. */
+    readonly controller?: RecordsController;
+}): UseEverfurRecordsState;
+
+interface EverfurRecordsProps {
+    readonly petRef: PetRef;
+    /** Host/test seam: inject a controller instead of acquiring one from the runtime. */
+    readonly controller?: RecordsController;
+    /** Host file picker: resolves a picked FileHandle (native document picker lives in the host app). */
+    readonly onPickDocument?: () => Promise<FileHandle | null>;
+    /** The consent-text version the grant CTA records (host/product owned). */
+    readonly consentVersion?: string;
+    readonly style?: StyleProp<ViewStyle>;
+}
+declare function EverfurRecords(props: EverfurRecordsProps): ReactNode;
+
+export { type ConsentState, type CreateUploadRequestInput, DocumentId, EverfurError, EverfurRecords, type EverfurRecordsProps, EverfurResult, FileHandle, type GrantConsentInput, PetRef, RECORDS_TERMINAL, type RecordDocumentMeta, type RecordEntity, type RecordForwardItem, type RecordIdentityField, type RecordOrigin, type RecordSeries, type RecordSeriesPoint, type RecordsController, type RecordsDenialReason, RecordsRequestId, type RecordsRequestStatus, type RecordsRequestView, type RecordsStatus, type RecordsView, type UploadDocumentInput, type UploadedDocument, type UseEverfurRecordsState, isTerminalStatus, recordsDenialReasonOf, useEverfurRecords };

package/dist/records/index.d.ts

@@ -0,0 +1,224 @@
+import { f as EverfurError, E as EverfurResult } from '../EverfurResult-D92-uL82.js';
+export { g as EverfurErrorCategory, a as EverfurErrorCode } from '../EverfurResult-D92-uL82.js';
+import { P as PetRef, R as RecordsRequestId, D as DocumentId } from '../ids-CJ1S6adf.js';
+export { B as Brand, _ as __brand } from '../ids-CJ1S6adf.js';
+import { F as FileHandle } from '../FilePort-BabWrv7I.js';
+import { ReactNode } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+
+/**
+ * The partner-scoped projection of the backend records-request status (records_schemas.py). The internal
+ * `dispatching` / `parsing_failed` / `review_email_failed` values are already collapsed by the backend
+ * `from_db_status`; the clinic-dispatch statuses are out of partner scope (§0) and never appear here.
+ */
+type RecordsRequestStatus = 'awaiting_upload' | 'received' | 'parsing' | 'in_review' | 'published' | 'failed' | 'revoked';
+/** Terminal statuses: polling stops here. */
+declare const RECORDS_TERMINAL: readonly RecordsRequestStatus[];
+declare function isTerminalStatus(status: RecordsRequestStatus): boolean;
+interface RecordsRequestView {
+    readonly id: RecordsRequestId;
+    readonly petRef: PetRef;
+    readonly status: RecordsRequestStatus;
+    /** BE-authored copy, rendered verbatim (dumb-renderer rule). */
+    readonly statusLabel: string;
+    /**
+     * DEAD, measured 2026-08-22: no plane sends it and nothing in this SDK reads it. The widget
+     * `RecordsRequestResponse` omits it, the consumer `RecordsRequestSummary` has no such field either, and a
+     * grep of `src/` finds zero render consumers - so it is always the mapper's `0` default.
+     *
+     * Deliberately NOT deleted here: removing a non-optional public field is a breaking change that needs a
+     * major bump, which is a release decision. Documented so nobody reads a count off it.
+     */
+    readonly documentCount: number;
+    /** facts extracted but awaiting review (badge "N being reviewed"). */
+    readonly heldItemCount: number;
+    /** ISO; null before first upload. */
+    readonly receivedAt: string | null;
+    /** drives the timeline "reading your records" step. */
+    readonly parsingStartedAt: string | null;
+    /** non-null == a parse gap occurred (§5, honest, not silent). */
+    readonly reviewStartedAt: string | null;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+interface UploadedDocument {
+    readonly documentId: DocumentId;
+    readonly requestId: RecordsRequestId;
+    /** uploads NEVER auto-bind / auto-publish. */
+    readonly status: 'received';
+}
+/** One redacted identity row (name / species / breed / owner-safe field). Provenance absent. */
+interface RecordIdentityField {
+    readonly label: string;
+    readonly value: string;
+}
+/**
+ * Who produced a reading. `owner_reported` is owner-entered (a home scale, typed into the pet profile);
+ * `clinic_document` is extracted from a vet document. The two now share one series, so a clinician reading a
+ * weight can tell them apart before dosing from it.
+ *
+ * A value this build does not know folds to `null` (unlabelled), never to a guess - see `normalizeOrigin`.
+ * `null` therefore means "the backend did not say", NOT "clinic".
+ */
+type RecordOrigin = 'owner_reported' | 'clinic_document';
+/**
+ * One extracted clinical fact. No `raw_value` / `source_span` / `source_bbox` / `source_page` /
+ * `source_doc_id` / `value_source` / `extraction_method` / `source_precedence` members - `origin` is the only
+ * provenance-adjacent field, and it is a display label (see `RecordOrigin`).
+ */
+interface RecordEntity {
+    readonly key: string;
+    readonly category: string;
+    readonly label: string;
+    readonly value: string | null;
+    readonly unit: string | null;
+    readonly observedAt: string | null;
+    readonly status: string | null;
+    /** Who measured it. `null` when the backend did not label it (an older backend never does). */
+    readonly origin: RecordOrigin | null;
+}
+interface RecordSeriesPoint {
+    readonly at: string;
+    readonly value: number | null;
+    readonly display: string | null;
+    /** Who measured this reading. `null` when the backend did not label it - never assume `clinic_document`. */
+    readonly origin: RecordOrigin | null;
+}
+/** A time series of one entity (e.g. a weight trend). */
+interface RecordSeries {
+    readonly key: string;
+    readonly label: string;
+    readonly points: readonly RecordSeriesPoint[];
+}
+/** A forward-looking item (a due vaccine / follow-up). */
+interface RecordForwardItem {
+    readonly title: string;
+    readonly detail: string | null;
+    readonly dueAt: string | null;
+}
+/** Metadata for one source document, keyed by its id. No raw bytes / provenance. */
+interface RecordDocumentMeta {
+    readonly docId: string;
+    readonly title: string | null;
+    readonly pageCount: number | null;
+    readonly receivedAt: string | null;
+}
+/**
+ * The parsed record, ALREADY partner-redacted server-side (§5). `isEmpty` is the normal pre-parse render;
+ * `withheld` is the §5 fail-closed suppression (redaction could not be proven safe) and renders the WITHHELD
+ * state, never empty, never raw.
+ */
+interface RecordsView {
+    readonly petRef: PetRef;
+    readonly schemaVersion: string;
+    readonly isEmpty: boolean;
+    readonly withheld: boolean;
+    readonly generatedAt: string | null;
+    readonly identity: readonly RecordIdentityField[];
+    readonly entities: readonly RecordEntity[];
+    readonly entitySeries: readonly RecordSeries[];
+    readonly forwardLooking: readonly RecordForwardItem[];
+    readonly documents: Readonly<Record<string, RecordDocumentMeta>>;
+    /** BE-authored not-medical-advice notice, rendered verbatim. */
+    readonly disclaimer: string;
+}
+interface ConsentState {
+    readonly petRef: PetRef;
+    readonly granted: boolean;
+    /** consent-text version the user agreed to. */
+    readonly version: string | null;
+    readonly grantedAt: string | null;
+}
+interface CreateUploadRequestInput {
+    readonly petRef: PetRef;
+    /** /^[A-Za-z0-9._-]{8,128}$/ (§3.1). Idempotent: a replay returns the SAME request. */
+    readonly idempotencyKey: string;
+}
+interface GrantConsentInput {
+    readonly petRef: PetRef;
+    readonly consentVersion: string;
+    readonly idempotencyKey: string;
+}
+/**
+ * Why a records read/write was access-denied (all fold to `EverfurErrorCode = 'accessDenied'`, §7). The
+ * coarse reason selects the recovery affordance: `consent_required` -> consent CTA, `session_required` ->
+ * establish-session CTA, `entitlement` -> the CapabilityGate disabled surface.
+ */
+type RecordsDenialReason = 'consent_required' | 'session_required' | 'entitlement';
+/** Read the records denial reason off any settled error, defensively (null when absent). */
+declare function recordsDenialReasonOf(error: EverfurError | null): RecordsDenialReason | null;
+
+interface UploadDocumentInput {
+    readonly requestId: RecordsRequestId;
+    readonly file: FileHandle;
+    readonly onProgress?: (fraction: number) => void;
+    readonly signal?: AbortSignal;
+}
+interface RecordsController {
+    /** Create the self-upload request. Idempotent on `idempotencyKey`. Lands `awaiting_upload`. */
+    createUploadRequest(input: CreateUploadRequestInput): Promise<EverfurResult<RecordsRequestView>>;
+    /** Two-phase presigned upload of ONE document (§3.2). Bytes go DIRECT to S3. Resolves at `received`. */
+    uploadDocument(input: UploadDocumentInput): Promise<EverfurResult<UploadedDocument>>;
+    /** Poll one request's parse lifecycle. */
+    getRequest(id: RecordsRequestId): Promise<EverfurResult<RecordsRequestView>>;
+    /** All of this user's requests, newest-first (server-ordered). */
+    listRequests(): Promise<EverfurResult<readonly RecordsRequestView[]>>;
+    /** The parsed, partner-redacted record. Consent-gated + redaction-fail-closed. */
+    getRecord(pet: PetRef): Promise<EverfurResult<RecordsView>>;
+    /** Consent read-back. Never a hard failure for an absent row -> `granted:false`. */
+    getConsent(pet: PetRef): Promise<EverfurResult<ConsentState>>;
+    /** Grant content-exposure consent. Fail-closed audited server-side. Idempotent. */
+    grantConsent(input: GrantConsentInput): Promise<EverfurResult<ConsentState>>;
+    /** Revoke consent (prospective). Drops any cached record for the pet from memory. Idempotent. */
+    revokeConsent(pet: PetRef): Promise<EverfurResult<ConsentState>>;
+    /** The last record read for a pet, held in memory only; cleared on revoke. Null when none. */
+    peekCachedRecord(pet: PetRef): RecordsView | null;
+    /** Emit `records.capability.denied` (the rn CapabilityGate disabled surface calls this once, R12). */
+    reportCapabilityDenied(pet: PetRef | null): void;
+}
+
+type RecordsStatus = 'loading' | 'empty' | 'error' | 'populated';
+interface UseEverfurRecordsState {
+    readonly status: RecordsStatus;
+    readonly record: RecordsView | null;
+    readonly requests: readonly RecordsRequestView[];
+    /** the most-recent request, whose timeline the populated state renders. */
+    readonly activeRequest: RecordsRequestView | null;
+    readonly consent: ConsentState | null;
+    readonly error: EverfurError | null;
+    /** drives the recovery affordance: consent CTA / establish-session CTA / disabled. */
+    readonly denialReason: RecordsDenialReason | null;
+    /** §5.1 fail-closed suppression: render the withheld notice, never empty, never raw. */
+    readonly withheld: boolean;
+    readonly isUploading: boolean;
+    readonly uploadProgress: number | null;
+    /** Create a self-upload request the user attaches documents to. */
+    createRequest(idempotencyKey: string): Promise<EverfurResult<RecordsRequestView>>;
+    /** Two-phase presigned upload of one document to the active request. */
+    uploadDocument(requestId: RecordsRequestView['id'], file: FileHandle): Promise<EverfurResult<UploadedDocument>>;
+    /** Grant content-exposure consent, then fetch the record. */
+    grantConsent(consentVersion: string, idempotencyKey: string): Promise<EverfurResult<ConsentState>>;
+    /** Revoke consent (prospective); drops the record from view. */
+    revokeConsent(): Promise<EverfurResult<ConsentState>>;
+    /** Re-run the surface fetch (error retry). */
+    refresh(): void;
+}
+declare function useEverfurRecords(opts: {
+    readonly petRef: PetRef;
+    /** Host/test seam: inject a controller directly instead of acquiring one from the runtime. */
+    readonly controller?: RecordsController;
+}): UseEverfurRecordsState;
+
+interface EverfurRecordsProps {
+    readonly petRef: PetRef;
+    /** Host/test seam: inject a controller instead of acquiring one from the runtime. */
+    readonly controller?: RecordsController;
+    /** Host file picker: resolves a picked FileHandle (native document picker lives in the host app). */
+    readonly onPickDocument?: () => Promise<FileHandle | null>;
+    /** The consent-text version the grant CTA records (host/product owned). */
+    readonly consentVersion?: string;
+    readonly style?: StyleProp<ViewStyle>;
+}
+declare function EverfurRecords(props: EverfurRecordsProps): ReactNode;
+
+export { type ConsentState, type CreateUploadRequestInput, DocumentId, EverfurError, EverfurRecords, type EverfurRecordsProps, EverfurResult, FileHandle, type GrantConsentInput, PetRef, RECORDS_TERMINAL, type RecordDocumentMeta, type RecordEntity, type RecordForwardItem, type RecordIdentityField, type RecordOrigin, type RecordSeries, type RecordSeriesPoint, type RecordsController, type RecordsDenialReason, RecordsRequestId, type RecordsRequestStatus, type RecordsRequestView, type RecordsStatus, type RecordsView, type UploadDocumentInput, type UploadedDocument, type UseEverfurRecordsState, isTerminalStatus, recordsDenialReasonOf, useEverfurRecords };