feat(supabase): animals and relations access layer

animals.ts: POST search with species filter and a probe row, read by id with
explicit columns, create with the optional first client in one call, update,
archive. relations.ts: an animal's relations in one select (voided left out),
create, end, dates, void. Kinds duplicate_relation and already_ended added.
This commit is contained in:
bchanot committed 2026-10-26 17:11:23 +01:00
1 parent 3c2b503fc9
commit e22357630f
7 files changed
+1612 -12

No files matched your search

+235
View File
@@ -0,0 +1,235 @@
import { z } from 'zod'
import type { FaunosteoClient } from './client'
import type { Database, Tables } from './database.types'
import {
RevisionSchema,
type AnimalRelationRole,
type NameCursor,
} from './clients'
import {
failRecord,
parseRecordAnswer,
UUID_PATTERN,
type RecordPage,
} from './records'
/**
* Browser side of the animals of a workspace (contract §5.2, §8.3, §9.3): one
* read by id under RLS with an explicit column list, the POST search, the
* three write RPCs. `create_animal` takes the optional initial relation in the
* same transaction, so an animal and its first client are never half made.
* The database rules decide; every failure is a RecordFailure of a closed kind.
*/
/** Columns the page reads; the derived keys and the request digest stay server-side. */
export const ANIMAL_COLUMNS =
'id, name, species_id, species_detail, sex, breed, birth_year, birth_date, revision, archived_at, created_at, updated_at'
export type AnimalRecord = Pick<
Tables<'animals'>,
| 'id'
| 'name'
| 'species_id'
| 'species_detail'
| 'sex'
| 'breed'
| 'birth_year'
| 'birth_date'
| 'revision'
| 'archived_at'
| 'created_at'
| 'updated_at'
>
/** The seven fields an animal is created or replaced with; an absent value is null, never ''. */
export type AnimalFields = Pick<
AnimalRecord,
| 'name'
| 'species_id'
| 'species_detail'
| 'sex'
| 'breed'
| 'birth_year'
| 'birth_date'
>
const AnimalListItemSchema = z.object({
id: z.string().uuid(),
name: z.string(),
species_id: z.string(),
species_detail: z.string().nullable(),
sex: z.enum(['male', 'female', 'unknown']),
breed: z.string().nullable(),
birth_year: z.number().int().nullable(),
archived_at: z.string().nullable(),
name_key: z.string(),
/** The first three current owners in name order, archived clients flagged. */
current_owners: z.array(
z.object({
client_id: z.string().uuid(),
display_name: z.string(),
archived: z.boolean(),
}),
),
current_owner_count: z.number().int(),
})
export type AnimalListItem = z.infer<typeof AnimalListItemSchema>
export interface AnimalSearch {
workspaceId: string
/** Trimmed by the server; 0 to 100 characters. */
query: string
/** A species id, or null for every species. */
speciesId: string | null
archived: boolean
/** 1 to 99; one more row is asked to know whether a next page exists. */
pageSize?: number
after?: NameCursor | null
}
/** One page of `search_animals` (POST: the term stays out of the URL). */
export async function searchAnimals(
client: FaunosteoClient,
search: AnimalSearch,
): Promise<RecordPage<AnimalListItem, NameCursor>> {
const size = search.pageSize ?? 25
const { data, error, status } = await client.rpc('search_animals', {
workspace_id: search.workspaceId,
query: search.query,
species_filter: search.speciesId ?? undefined,
archived: search.archived,
page_size: size + 1,
after_name_key: search.after?.nameKey,
after_id: search.after?.id,
})
if (error) failRecord(error, status)
const found = parseRecordAnswer(z.array(AnimalListItemSchema), data)
const rows = found.slice(0, size)
const last = rows.at(-1)
return {
rows,
next:
found.length > size && last
? { nameKey: last.name_key, id: last.id }
: null,
}
}
/** The animal, or null for an unknown id and for an id of another workspace alike. */
export async function fetchAnimalRecord(
client: FaunosteoClient,
animalId: string,
): Promise<AnimalRecord | null> {
if (!UUID_PATTERN.test(animalId)) return null
const { data, error, status } = await client
.from('animals')
.select(ANIMAL_COLUMNS)
.eq('id', animalId)
.maybeSingle()
if (error) failRecord(error, status)
return data
}
/** The client the animal is linked to at creation, with an explicit role. */
export interface InitialRelation {
clientId: string
relationRole: AnimalRelationRole
/** YYYY-MM-DD when known, else null (never filled by default). */
startedOn: string | null
}
export interface CreateAnimalInput {
workspaceId: string
/** One per creation intent, sent again on a retry: the server answers the first animal. */
requestId: string
fields: AnimalFields
relation: InitialRelation | null
}
const CreatedAnimalSchema = z.object({
id: z.string().uuid(),
revision: z.number().int(),
relation_id: z.string().uuid().nullable(),
})
/** Years and dates travel as text: the RPC parses them and answers invalid_input on a bad one. */
const yearText = (year: number | null) =>
year === null ? undefined : String(year)
export async function createAnimalRecord(
client: FaunosteoClient,
input: CreateAnimalInput,
): Promise<{ id: string; revision: number; relationId: string | null }> {
const f = input.fields
const r = input.relation
const { data, error, status } = await client.rpc('create_animal', {
workspace_id: input.workspaceId,
create_request_id: input.requestId,
name: f.name,
species_id: f.species_id,
sex: f.sex,
species_detail: f.species_detail ?? undefined,
breed: f.breed ?? undefined,
birth_year: yearText(f.birth_year),
birth_date: f.birth_date ?? undefined,
client_id: r?.clientId,
relation_role: r?.relationRole,
started_on: r?.startedOn ?? undefined,
})
if (error) failRecord(error, status)
const created = parseRecordAnswer(CreatedAnimalSchema, data)
return {
id: created.id,
revision: created.revision,
relationId: created.relation_id,
}
}
type UpdateAnimalArgs = Database['public']['Functions']['update_animal']['Args']
export interface UpdateAnimalInput {
animalId: string
expectedRevision: number
fields: AnimalFields
}
/** Replaces the seven fields at `expectedRevision`; a stale revision is `conflict`. */
export async function updateAnimalRecord(
client: FaunosteoClient,
input: UpdateAnimalInput,
): Promise<{ revision: number }> {
const f = input.fields
// The update RPC has no defaults: every field is sent, null included (see
// updateClientRecord for why the generated type is widened this way).
const args = {
animal_id: input.animalId,
expected_revision: input.expectedRevision,
name: f.name,
species_id: f.species_id,
sex: f.sex,
species_detail: f.species_detail,
breed: f.breed,
birth_year: f.birth_year === null ? null : String(f.birth_year),
birth_date: f.birth_date,
} satisfies { [K in keyof UpdateAnimalArgs]: UpdateAnimalArgs[K] | null }
const { data, error, status } = await client.rpc(
'update_animal',
args as UpdateAnimalArgs,
)
if (error) failRecord(error, status)
return parseRecordAnswer(RevisionSchema, data)
}
/** Archives or restores; the relations are kept either way (contract §7.1). */
export async function setAnimalArchived(
client: FaunosteoClient,
animalId: string,
archived: boolean,
): Promise<{ revision: number }> {
const { data, error, status } = await client.rpc('set_animal_archived', {
animal_id: animalId,
archived,
})
if (error) failRecord(error, status)
return parseRecordAnswer(RevisionSchema, data)
}
+8 -12
View File
@@ -3,6 +3,7 @@ import type { FaunosteoClient } from './client'
import type { Database, Enums, Tables } from './database.types'
import {
failRecord,
parseRecordAnswer,
RecordFailure,
UUID_PATTERN,
type RecordPage,
@@ -132,13 +133,8 @@ const CreatedSchema = z.object({
id: z.string().uuid(),
revision: z.number().int(),
})
const RevisionSchema = z.object({ revision: z.number().int() })
function parsed<T>(schema: z.ZodType<T>, data: unknown): T {
const result = schema.safeParse(data)
if (!result.success) throw new RecordFailure('unavailable', result.error)
return result.data
}
/** The answer of every update, archive and relation write RPC. */
export const RevisionSchema = z.object({ revision: z.number().int() })
export interface CreateClientInput {
workspaceId: string
@@ -166,7 +162,7 @@ export async function createClientRecord(
country: f.country ?? undefined,
})
if (error) failRecord(error, status)
return parsed(CreatedSchema, data)
return parseRecordAnswer(CreatedSchema, data)
}
type UpdateClientArgs = Database['public']['Functions']['update_client']['Args']
@@ -204,7 +200,7 @@ export async function updateClientRecord(
args as UpdateClientArgs,
)
if (error) failRecord(error, status)
return parsed(RevisionSchema, data)
return parseRecordAnswer(RevisionSchema, data)
}
export async function setClientArchived(
@@ -217,7 +213,7 @@ export async function setClientArchived(
archived,
})
if (error) failRecord(error, status)
return parsed(RevisionSchema, data)
return parseRecordAnswer(RevisionSchema, data)
}
const ArchivePreviewSchema = z.object({
@@ -235,7 +231,7 @@ export async function fetchClientArchivePreview(
client_id: clientId,
})
if (error) failRecord(error, status)
return parsed(ArchivePreviewSchema, data)
return parseRecordAnswer(ArchivePreviewSchema, data)
}
const ClientAnimalSchema = z.object({
@@ -274,7 +270,7 @@ export async function listClientAnimals(
after_id: options.after?.relationId,
})
if (error) failRecord(error, status)
const rows = parsed(z.array(ClientAnimalSchema), data)
const rows = parseRecordAnswer(z.array(ClientAnimalSchema), data)
const page = rows.slice(0, size)
const last = page.at(-1)
return {
+29
View File
@@ -93,6 +93,8 @@ export {
RECORD_FAILURE_KINDS,
RecordFailure,
classifyRecordError,
parseRecordAnswer,
UUID_PATTERN,
type RecordFailureKind,
type RecordPage,
} from './records'
@@ -121,6 +123,33 @@ export {
type RelationCursor,
type UpdateClientInput,
} from './clients'
export {
ANIMAL_COLUMNS,
createAnimalRecord,
fetchAnimalRecord,
searchAnimals,
setAnimalArchived,
updateAnimalRecord,
type AnimalFields,
type AnimalListItem,
type AnimalRecord,
type AnimalSearch,
type CreateAnimalInput,
type InitialRelation,
type UpdateAnimalInput,
} from './animals'
export {
ANIMAL_RELATION_COLUMNS,
createAnimalClientRelation,
endAnimalClientRelation,
fetchAnimalRelations,
updateAnimalClientRelation,
voidAnimalClientRelation,
type AnimalRelationItem,
type CreateRelationInput,
type EndRelationInput,
type UpdateRelationDatesInput,
} from './relations'
export {
ANIMAL_FIELD_LIMITS,
BIRTH_YEAR_MIN,
+13
View File
@@ -1,3 +1,5 @@
import type { z } from 'zod'
/**
* Closed failure kinds of the V1-1 record reads and RPCs (clients, animals,
* relations): contract docs/development/V1-1_OWNERS_ANIMALS.md §9.4. The
@@ -14,6 +16,8 @@ export const RECORD_FAILURE_KINDS = [
'limit_reached',
'rate_limited',
'invalid_input',
'duplicate_relation',
'already_ended',
'session_expired',
'network',
'unavailable',
@@ -37,6 +41,8 @@ const RPC_MESSAGE_KINDS: ReadonlySet<string> = new Set([
'limit_reached',
'rate_limited',
'invalid_input',
'duplicate_relation',
'already_ended',
])
interface PostgrestLikeError {
@@ -70,6 +76,13 @@ export function failRecord(error: unknown, status?: number): never {
throw new RecordFailure(classifyRecordError(error, status), error)
}
/** The RPC answer checked against its contract; a different shape is `unavailable`. */
export function parseRecordAnswer<T>(schema: z.ZodType<T>, data: unknown): T {
const result = schema.safeParse(data)
if (!result.success) throw new RecordFailure('unavailable', result.error)
return result.data
}
/** Ids are uuids: anything else is answered as unknown without a request. */
export const UUID_PATTERN =
/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+165
View File
@@ -0,0 +1,165 @@
import { z } from 'zod'
import type { FaunosteoClient } from './client'
import type { Database } from './database.types'
import { RevisionSchema } from './clients'
import { failRecord, parseRecordAnswer, UUID_PATTERN } from './records'
/**
* Browser side of the relations between an animal and its clients (contract
* §5.3, §8.3, §9.3). The animal page reads them with one select by animal id
* (at most 200 by the cap), the client embedded through the composite foreign
* key; voided relations are left out, as every V1-1 screen leaves them out.
* Writes go through the four relation RPCs only.
*/
const RELATION_ROLES = ['owner', 'keeper', 'contact'] as const
/**
* `ended_at` tells a current relation from a former one; it is a technical
* time, never shown as the end date (`ended_on` is).
*/
export const ANIMAL_RELATION_COLUMNS =
'id, relation_role, started_on, ended_on, ended_at, revision, client:clients!animal_client_relations_client_fk(id, kind, display_name, phone, email, archived_at)'
const AnimalRelationSchema = z.object({
id: z.string().uuid(),
relation_role: z.enum(RELATION_ROLES),
started_on: z.string().nullable(),
ended_on: z.string().nullable(),
ended_at: z.string().nullable(),
revision: z.number().int(),
client: z.object({
id: z.string().uuid(),
kind: z.enum(['person', 'organization']),
display_name: z.string(),
phone: z.string().nullable(),
email: z.string().nullable(),
archived_at: z.string().nullable(),
}),
})
export type AnimalRelationItem = z.infer<typeof AnimalRelationSchema>
/** The cap of relations per animal (contract §10), ended and voided included. */
const RELATIONS_PER_ANIMAL = 200
/** The animal's relations that existed (voided ones left out), in creation order. */
export async function fetchAnimalRelations(
client: FaunosteoClient,
animalId: string,
): Promise<AnimalRelationItem[]> {
if (!UUID_PATTERN.test(animalId)) return []
const { data, error, status } = await client
.from('animal_client_relations')
.select(ANIMAL_RELATION_COLUMNS)
.eq('animal_id', animalId)
.is('voided_at', null)
.order('created_at')
.order('id')
.limit(RELATIONS_PER_ANIMAL)
if (error) failRecord(error, status)
return parseRecordAnswer(z.array(AnimalRelationSchema), data)
}
export interface CreateRelationInput {
animalId: string
clientId: string
/** One per creation intent, sent again on a retry: the server answers the first relation. */
requestId: string
relationRole: (typeof RELATION_ROLES)[number]
/** YYYY-MM-DD when known, else null (never filled by default). */
startedOn: string | null
}
const CreatedSchema = z.object({
id: z.string().uuid(),
revision: z.number().int(),
})
/** A current relation between an active animal and an active client of one workspace. */
export async function createAnimalClientRelation(
client: FaunosteoClient,
input: CreateRelationInput,
): Promise<{ id: string; revision: number }> {
const { data, error, status } = await client.rpc(
'create_animal_client_relation',
{
animal_id: input.animalId,
client_id: input.clientId,
create_request_id: input.requestId,
relation_role: input.relationRole,
started_on: input.startedOn ?? undefined,
},
)
if (error) failRecord(error, status)
return parseRecordAnswer(CreatedSchema, data)
}
export interface EndRelationInput {
relationId: string
expectedRevision: number
/** The real end date when known; null records the end without one. */
endedOn: string | null
}
/** Ends a current relation: it stays as a former one, with its dates. */
export async function endAnimalClientRelation(
client: FaunosteoClient,
input: EndRelationInput,
): Promise<{ revision: number }> {
const { data, error, status } = await client.rpc(
'end_animal_client_relation',
{
relation_id: input.relationId,
expected_revision: input.expectedRevision,
ended_on: input.endedOn ?? undefined,
},
)
if (error) failRecord(error, status)
return parseRecordAnswer(RevisionSchema, data)
}
type UpdateRelationArgs =
Database['public']['Functions']['update_animal_client_relation']['Args']
export interface UpdateRelationDatesInput {
relationId: string
expectedRevision: number
startedOn: string | null
/** Only on an ended relation; the server refuses one on a current relation. */
endedOn: string | null
}
/** Corrects the dates; both are sent, an empty one is null (the RPC has no defaults). */
export async function updateAnimalClientRelation(
client: FaunosteoClient,
input: UpdateRelationDatesInput,
): Promise<{ revision: number }> {
const args = {
relation_id: input.relationId,
expected_revision: input.expectedRevision,
started_on: input.startedOn,
ended_on: input.endedOn,
} satisfies { [K in keyof UpdateRelationArgs]: UpdateRelationArgs[K] | null }
const { data, error, status } = await client.rpc(
'update_animal_client_relation',
args as UpdateRelationArgs,
)
if (error) failRecord(error, status)
return parseRecordAnswer(RevisionSchema, data)
}
/** Voids a relation entered by mistake (N4): kept, frozen and shown nowhere; never a deletion. */
export async function voidAnimalClientRelation(
client: FaunosteoClient,
input: { relationId: string; expectedRevision: number },
): Promise<{ revision: number }> {
const { data, error, status } = await client.rpc(
'void_animal_client_relation',
{
relation_id: input.relationId,
expected_revision: input.expectedRevision,
},
)
if (error) failRecord(error, status)
return parseRecordAnswer(RevisionSchema, data)
}