@fabrika/app 0.9.0-dev.1 → 0.9.0-dev.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +32 -26
- package/skill/SKILL.md +46 -15
- package/skill/references/app-setup.md +43 -12
- package/skill/references/dev.md +5 -2
- package/skill/references/endpoint.md +39 -28
- package/skill/references/errors.md +50 -37
- package/skill/references/files.md +8 -4
- package/skill/references/jobs.md +39 -7
- package/skill/references/table-and-migration.md +47 -3
- package/skill/references/tests.md +61 -10
- package/skill/references/webhooks-links-connectors.md +1 -1
- package/src/build-recipe.ts +198 -0
- package/src/build.ts +60 -4
- package/src/bun.ts +181 -13
- package/src/cloudflare/application.ts +822 -0
- package/src/cloudflare/bindings.ts +159 -0
- package/src/cloudflare/export.ts +621 -0
- package/src/cloudflare/import.ts +888 -0
- package/src/cloudflare/maintenance.ts +518 -0
- package/src/cloudflare/names.ts +16 -0
- package/src/cloudflare/ops.ts +375 -0
- package/src/cloudflare/r2-files.ts +172 -0
- package/src/cloudflare/restore.ts +167 -0
- package/src/cloudflare/tracker.ts +192 -0
- package/src/cloudflare.ts +100 -146
- package/src/contract/app-id.ts +5 -0
- package/src/contract/artifact-schema.ts +9 -1
- package/src/contract/build.ts +40 -2
- package/src/contract/capability-cases.ts +30 -0
- package/src/contract/compile.ts +1 -0
- package/src/contract/containers.ts +19 -0
- package/src/contract/context.ts +35 -9
- package/src/contract/declaration.ts +2 -0
- package/src/contract/defaults.ts +22 -2
- package/src/contract/define.ts +29 -3
- package/src/contract/index.ts +1 -0
- package/src/contract/kit.ts +4 -1
- package/src/contract/platform.ts +3 -2
- package/src/contract/vocabulary.ts +26 -8
- package/src/dev/changes.ts +5 -43
- package/src/dev/contract-digest.ts +17 -0
- package/src/dev/index.ts +1 -1
- package/src/dev/launcher.ts +197 -41
- package/src/dev/output.ts +13 -3
- package/src/dev/wire.ts +11 -1
- package/src/disk-assets.ts +8 -3
- package/src/files/archive.ts +2 -2
- package/src/files/handle.ts +2 -1
- package/src/files/job-names.ts +12 -0
- package/src/files/kinds.ts +74 -32
- package/src/files/scan.ts +3 -4
- package/src/files/streams.ts +3 -1
- package/src/implement/anonymous.ts +12 -11
- package/src/implement/boot.ts +84 -27
- package/src/implement/bounded.ts +21 -2
- package/src/implement/capability.ts +16 -4
- package/src/implement/dispatch.ts +423 -178
- package/src/implement/failures.ts +59 -4
- package/src/implement/faults.ts +5 -1
- package/src/implement/index.ts +1 -0
- package/src/implement/invocation.ts +62 -11
- package/src/implement/principal.ts +25 -2
- package/src/implement/terminals.ts +93 -0
- package/src/implement/tokens.ts +4 -2
- package/src/implement/types.ts +22 -4
- package/src/implement/workload.ts +42 -16
- package/src/jobs/mail.ts +8 -0
- package/src/jobs/report.ts +5 -1
- package/src/jobs/runner.ts +702 -126
- package/src/jobs/schedule.ts +7 -1
- package/src/jobs/scrub.ts +14 -1
- package/src/jobs/types.ts +6 -0
- package/src/spa-fallback.ts +12 -0
- package/src/testing/endpoint-access.ts +331 -169
- package/src/testing/index.ts +1 -1
- package/src/testing/isolation.ts +8 -1
- package/src/testing/kit.ts +86 -4
- package/src/testing/policy-isolation.ts +2 -2
- package/src/testing/proxy.ts +15 -10
- package/types/src/agent-skill.d.ts +29 -0
- package/types/src/build-recipe.d.ts +70 -0
- package/types/src/build.d.ts +29 -0
- package/types/src/bun.d.ts +99 -0
- package/types/src/client/caller.d.ts +19 -0
- package/types/src/client/contract.d.ts +131 -0
- package/types/src/client/error-reporting.d.ts +66 -0
- package/types/src/client/index.d.ts +4 -0
- package/types/src/client/rpc.d.ts +14 -0
- package/types/src/client/share.d.ts +2 -0
- package/types/src/client/transport.d.ts +42 -0
- package/types/src/cloudflare/application.d.ts +73 -0
- package/types/src/cloudflare/bindings.d.ts +33 -0
- package/types/src/cloudflare/export.d.ts +16 -0
- package/types/src/cloudflare/import.d.ts +47 -0
- package/types/src/cloudflare/maintenance.d.ts +117 -0
- package/types/src/cloudflare/names.d.ts +11 -0
- package/types/src/cloudflare/ops.d.ts +81 -0
- package/types/src/cloudflare/r2-files.d.ts +9 -0
- package/types/src/cloudflare/restore.d.ts +9 -0
- package/types/src/cloudflare/tracker.d.ts +29 -0
- package/types/src/cloudflare.d.ts +43 -0
- package/types/src/contract/app-id.d.ts +2 -0
- package/types/src/contract/artifact-schema.d.ts +10 -0
- package/types/src/contract/attachment.d.ts +41 -0
- package/types/src/contract/build.d.ts +12 -0
- package/types/src/contract/capability-cases.d.ts +9 -0
- package/types/src/contract/compile.d.ts +11 -0
- package/types/src/contract/connect.d.ts +51 -0
- package/types/src/contract/containers.d.ts +3 -0
- package/types/src/contract/context.d.ts +525 -0
- package/types/src/contract/declaration.d.ts +307 -0
- package/types/src/contract/defaults.d.ts +226 -0
- package/types/src/contract/define.d.ts +376 -0
- package/types/src/contract/file.d.ts +44 -0
- package/types/src/contract/group.d.ts +274 -0
- package/types/src/contract/handled.d.ts +18 -0
- package/types/src/contract/index.d.ts +20 -0
- package/types/src/contract/kit.d.ts +211 -0
- package/types/src/contract/platform.d.ts +9 -0
- package/types/src/contract/problems.d.ts +14 -0
- package/types/src/contract/redirect.d.ts +25 -0
- package/types/src/contract/schema-from-shape.d.ts +10 -0
- package/types/src/contract/schema-shape.d.ts +5 -0
- package/types/src/contract/snapshot-source.d.ts +15 -0
- package/types/src/contract/token.d.ts +58 -0
- package/types/src/contract/vocabulary.d.ts +32 -0
- package/types/src/contract/webhook-binding.d.ts +24 -0
- package/types/src/contract/webhook-scheme.d.ts +23 -0
- package/types/src/dev/changes.d.ts +7 -0
- package/types/src/dev/contract-digest.d.ts +1 -0
- package/types/src/dev/index.d.ts +2 -0
- package/types/src/dev/launcher.d.ts +32 -0
- package/types/src/dev/output.d.ts +28 -0
- package/types/src/dev/wire.d.ts +126 -0
- package/types/src/disk-assets.d.ts +6 -0
- package/types/src/errors.d.ts +46 -0
- package/types/src/fetch.d.ts +7 -0
- package/types/src/files/archive.d.ts +26 -0
- package/types/src/files/clamscan.d.ts +32 -0
- package/types/src/files/handle.d.ts +107 -0
- package/types/src/files/job-names.d.ts +9 -0
- package/types/src/files/kinds.d.ts +112 -0
- package/types/src/files/scan.d.ts +78 -0
- package/types/src/files/sniff.d.ts +7 -0
- package/types/src/files/streams.d.ts +17 -0
- package/types/src/files/treatment.d.ts +18 -0
- package/types/src/from-row.d.ts +20 -0
- package/types/src/honeypot.d.ts +2 -0
- package/types/src/implement/anonymous.d.ts +24 -0
- package/types/src/implement/attachment.d.ts +14 -0
- package/types/src/implement/boot.d.ts +128 -0
- package/types/src/implement/bounded.d.ts +32 -0
- package/types/src/implement/browser-config.d.ts +19 -0
- package/types/src/implement/capability.d.ts +142 -0
- package/types/src/implement/challenge.d.ts +75 -0
- package/types/src/implement/client-address.d.ts +11 -0
- package/types/src/implement/connect.d.ts +67 -0
- package/types/src/implement/crashes.d.ts +31 -0
- package/types/src/implement/dispatch.d.ts +251 -0
- package/types/src/implement/egress.d.ts +14 -0
- package/types/src/implement/environment.d.ts +14 -0
- package/types/src/implement/failures.d.ts +58 -0
- package/types/src/implement/faults.d.ts +48 -0
- package/types/src/implement/headers.d.ts +7 -0
- package/types/src/implement/implement.d.ts +58 -0
- package/types/src/implement/index.d.ts +25 -0
- package/types/src/implement/invocation.d.ts +136 -0
- package/types/src/implement/membership.d.ts +201 -0
- package/types/src/implement/multipart.d.ts +36 -0
- package/types/src/implement/params.d.ts +7 -0
- package/types/src/implement/principal.d.ts +57 -0
- package/types/src/implement/project.d.ts +11 -0
- package/types/src/implement/public.d.ts +61 -0
- package/types/src/implement/serve.d.ts +25 -0
- package/types/src/implement/terminals.d.ts +33 -0
- package/types/src/implement/tokens.d.ts +49 -0
- package/types/src/implement/types.d.ts +263 -0
- package/types/src/implement/urls.d.ts +15 -0
- package/types/src/implement/verifiers.d.ts +19 -0
- package/types/src/implement/webhook.d.ts +55 -0
- package/types/src/implement/workload.d.ts +61 -0
- package/types/src/implement/xlsx.d.ts +6 -0
- package/types/src/index.d.ts +12 -0
- package/types/src/jobs/exception.d.ts +40 -0
- package/types/src/jobs/mail.d.ts +67 -0
- package/types/src/jobs/report.d.ts +56 -0
- package/types/src/jobs/runner.d.ts +218 -0
- package/types/src/jobs/schedule.d.ts +17 -0
- package/types/src/jobs/scrub.d.ts +12 -0
- package/types/src/jobs/types.d.ts +98 -0
- package/types/src/react/caller.d.ts +30 -0
- package/types/src/react/errors.d.ts +40 -0
- package/types/src/react/hooks.d.ts +110 -0
- package/types/src/react/index.d.ts +5 -0
- package/types/src/react/provider.d.ts +58 -0
- package/types/src/react/store.d.ts +68 -0
- package/types/src/react/testing.d.ts +28 -0
- package/types/src/react/types.d.ts +33 -0
- package/types/src/rpc/builder.d.ts +52 -0
- package/types/src/rpc/contract.d.ts +23 -0
- package/types/src/rpc/dispatcher.d.ts +11 -0
- package/types/src/rpc/types.d.ts +62 -0
- package/types/src/service/define.d.ts +42 -0
- package/types/src/service/index.d.ts +3 -0
- package/types/src/service/serve.d.ts +28 -0
- package/types/src/spa-fallback.d.ts +2 -0
- package/types/src/standard-schema.d.ts +55 -0
- package/types/src/testing/caller.d.ts +95 -0
- package/types/src/testing/challenge.d.ts +11 -0
- package/types/src/testing/dev.d.ts +97 -0
- package/types/src/testing/endpoint-access.d.ts +132 -0
- package/types/src/testing/index.d.ts +12 -0
- package/types/src/testing/isolation.d.ts +3 -0
- package/types/src/testing/kit.d.ts +207 -0
- package/types/src/testing/membership.d.ts +132 -0
- package/types/src/testing/policy-isolation.d.ts +113 -0
- package/types/src/testing/preload.d.ts +1 -0
- package/types/src/testing/proxy.d.ts +40 -0
- package/types/src/testing/runner.d.ts +8 -0
- package/types/src/testing/sample-file.d.ts +5 -0
- package/types/src/testing/status.d.ts +4 -0
- package/types/src/undumpable.d.ts +5 -0
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
import type { IamMembership } from '@fabrika/auth';
|
|
2
|
+
import { type ContractArtifact } from '@fabrika/auth-core';
|
|
3
|
+
import type { CapabilityAuthority } from '@fabrika/db/capability';
|
|
4
|
+
import { type DataAccess, type FrameworkTables, type LeaseFence, type Session } from '@fabrika/db/framework';
|
|
5
|
+
import { type StoredFileKinds } from '../files/kinds';
|
|
6
|
+
import { type CapabilityMint } from '../implement/capability';
|
|
7
|
+
import { type HandlerErrorSink } from '../implement/failures';
|
|
8
|
+
import type { ContractDatabase } from '../implement/implement';
|
|
9
|
+
import type { SignedTokens } from '../implement/tokens';
|
|
10
|
+
import { type AppUrl } from '../implement/urls';
|
|
11
|
+
import { type WorkloadCredential } from '../implement/workload';
|
|
12
|
+
import { type MailTransports } from './mail';
|
|
13
|
+
import type { OperationsReporter } from './report';
|
|
14
|
+
import { type CronSchedule } from './schedule';
|
|
15
|
+
/**
|
|
16
|
+
* The lease outlives an attempt's deadline by this much: the runner renews or finishes a timed-out attempt's lease,
|
|
17
|
+
* and no other run takes it over meanwhile. The attempt's writes stop at its deadline regardless.
|
|
18
|
+
*/
|
|
19
|
+
export declare const LEASE_GRACE_MS = 60000;
|
|
20
|
+
/** How often the serving process checks every job for a crashed run and for a schedule that stopped. */
|
|
21
|
+
export declare const JOB_CHECK_INTERVAL_MS = 60000;
|
|
22
|
+
/**
|
|
23
|
+
* A run the Cloudflare alarm started has one segment (`CLOUDFLARE_MAX_JOB_SEGMENT_MS`): its attempt ends this much
|
|
24
|
+
* before the segment, at most a tenth of it, so the finish runs inside the segment too.
|
|
25
|
+
*/
|
|
26
|
+
export declare const SEGMENT_FINISH_RESERVE_MS = 30000;
|
|
27
|
+
/**
|
|
28
|
+
* Why a run failed. Fixed codes only: an application error's name and message may carry a secret, so neither is
|
|
29
|
+
* ever logged or returned. Only the report to Operations carries them, scrubbed (ADR-0059).
|
|
30
|
+
*/
|
|
31
|
+
export type JobFailureCode = 'timeout' | 'lease_lost' | 'handler_failed'
|
|
32
|
+
/** The data layer refused a statement or an operation tree (`QueryRefusedError`): its reason names why. */
|
|
33
|
+
| 'query_refused'
|
|
34
|
+
/** A capability or a handle was refused: forged, ended, of other work, or of another kind than the call takes. */
|
|
35
|
+
| 'capability_refused'
|
|
36
|
+
/** The framework failed the attempt (`ServerFault`): its reason names why, as a request's 500 names it. */
|
|
37
|
+
| 'framework_fault'
|
|
38
|
+
/**
|
|
39
|
+
* The framework could not reach a service it needs (a `ServerFault` with status 503), as a request's 503 names it. IAM
|
|
40
|
+
* is the exception: met inside the handler as at the attempt's start, it is `iam_unavailable` or `unauthorized`.
|
|
41
|
+
*/
|
|
42
|
+
| 'unavailable' | 'driver_failed' | 'crashed'
|
|
43
|
+
/** IAM refused the job's key: the attempt mints no capability. */
|
|
44
|
+
| 'unauthorized'
|
|
45
|
+
/** IAM could not be asked for the job's token. */
|
|
46
|
+
| 'iam_unavailable'
|
|
47
|
+
/** The process stopped a kicked run while shutting down, or the object's maintenance stopped a run; the schedule runs it again. */
|
|
48
|
+
| 'stopped'
|
|
49
|
+
/** The transport refused a message the handler did not catch; `reason` is the `EmailDeliveryError` code. */
|
|
50
|
+
| 'mail_failed';
|
|
51
|
+
export type JobRunResult = {
|
|
52
|
+
readonly status: 'succeeded';
|
|
53
|
+
readonly attempts: number;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* `reason` is a framework failure's catalog key (`query_refused`, `capability_refused`, `framework_fault`,
|
|
57
|
+
* `unavailable`) or the `EmailDeliveryError` code (`mail_failed`), present only for one of those.
|
|
58
|
+
*/
|
|
59
|
+
| {
|
|
60
|
+
readonly status: 'failed';
|
|
61
|
+
readonly attempts: number;
|
|
62
|
+
readonly code: JobFailureCode;
|
|
63
|
+
readonly reason?: string;
|
|
64
|
+
}
|
|
65
|
+
/** Another run holds the lease: an overlapping run does not start. */
|
|
66
|
+
| {
|
|
67
|
+
readonly status: 'skipped';
|
|
68
|
+
};
|
|
69
|
+
/** The runner's waits; the lease's times are always the database's. */
|
|
70
|
+
export interface JobClock {
|
|
71
|
+
/** Resolves after `ms`, or as soon as `signal` aborts. */
|
|
72
|
+
wait(ms: number, signal: AbortSignal): Promise<void>;
|
|
73
|
+
/** In [0, 1): the jitter of a retry's backoff. */
|
|
74
|
+
random(): number;
|
|
75
|
+
/** Epoch milliseconds: what an attempt's deadline is measured on; `Date.now()` when absent. */
|
|
76
|
+
now?(): number;
|
|
77
|
+
}
|
|
78
|
+
export interface JobRunOptions {
|
|
79
|
+
readonly clock?: JobClock;
|
|
80
|
+
/** Where failures and missed runs go; by default the one `boot` built from `FABRIKA_OPERATIONS_DSN`. */
|
|
81
|
+
readonly reporter?: OperationsReporter;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* A job the framework runs itself under a reserved name (`FILE_SCAN_JOB`): no handler, no key, no capability, one
|
|
85
|
+
* attempt. It holds its lease like an application job, and every write of its run is fenced by it.
|
|
86
|
+
*/
|
|
87
|
+
export interface FrameworkJob {
|
|
88
|
+
readonly name: string;
|
|
89
|
+
readonly schedule: string;
|
|
90
|
+
readonly timeoutMs: number;
|
|
91
|
+
/** One run; `signal` aborts when the attempt's deadline passes. A throw fails the run. */
|
|
92
|
+
run(reporter: OperationsReporter, signal: AbortSignal): Promise<void>;
|
|
93
|
+
}
|
|
94
|
+
/** The contract's jobs, bound to their handlers by `boot`, and the framework's own. */
|
|
95
|
+
export interface ContractJobs {
|
|
96
|
+
/** The contract's `c.cron` jobs; `run` also takes the name of a framework job the contract needs. */
|
|
97
|
+
readonly names: readonly string[];
|
|
98
|
+
/** Every job bound to run, the framework's included, with its schedule: what a minute tick runs when due. */
|
|
99
|
+
readonly scheduled: readonly {
|
|
100
|
+
readonly name: string;
|
|
101
|
+
readonly schedule: CronSchedule;
|
|
102
|
+
}[];
|
|
103
|
+
run(name: string, options?: JobRunOptions): Promise<JobRunResult>;
|
|
104
|
+
/**
|
|
105
|
+
* Registers every job (its first-seen time), reports a run that crashed and a job that has not succeeded within
|
|
106
|
+
* twice its period. The serving process calls it every `JOB_CHECK_INTERVAL_MS`; it never throws.
|
|
107
|
+
*/
|
|
108
|
+
check(options?: Pick<JobRunOptions, 'reporter'>): Promise<void>;
|
|
109
|
+
/**
|
|
110
|
+
* The serving process's wake timer on Bun, where crontab runs the schedule: reaps a crashed holder of every job and
|
|
111
|
+
* kicks each contract job with a due wake through the kick path, handing each kick to `track` until it ended. Answers
|
|
112
|
+
* how long until a wake is due next on the database's clock (0 while one still is), `null` when none is pending. The
|
|
113
|
+
* first call deletes the wakes of jobs the contract no longer declares.
|
|
114
|
+
*/
|
|
115
|
+
wake(track: (kick: Promise<void>) => void): Promise<number | null>;
|
|
116
|
+
/** What the Cloudflare object's alarm drives the jobs through; `null` without `@fabrika/db`. */
|
|
117
|
+
readonly scheduler: JobScheduler | null;
|
|
118
|
+
}
|
|
119
|
+
/** What the scheduler's `take` did for one job in the alarm's transaction. */
|
|
120
|
+
export interface TakenLease {
|
|
121
|
+
/** The lease a run of the job now holds, for `run`; `null` when nothing was due or another run holds it. */
|
|
122
|
+
readonly fence: LeaseFence | null;
|
|
123
|
+
/** Whether a crashed holder's lease was freed: `crashed` reports it once the transaction committed. */
|
|
124
|
+
readonly reaped: boolean;
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* The jobs as the Cloudflare object's alarm drives them (ADR-0065 §5): over the wakes and leases of the object's
|
|
128
|
+
* storage, every time on the database's clock. The object holds the transactions and arms the alarm.
|
|
129
|
+
*/
|
|
130
|
+
export interface JobScheduler {
|
|
131
|
+
/** Every job bound to run, the framework's included. */
|
|
132
|
+
readonly jobs: readonly string[];
|
|
133
|
+
/**
|
|
134
|
+
* Startup repair: reaps and reports every crashed run, of a job the contract no longer declares too; registers every
|
|
135
|
+
* job and surveils it (as `check`), deletes the wakes of jobs the contract no longer declares and the cron wakes of a
|
|
136
|
+
* changed expression, and keeps one cron wake per job at its next fire; an overdue one stays, so missed runs coalesce
|
|
137
|
+
* into one. `false` when the object's barrier admits no job.
|
|
138
|
+
*/
|
|
139
|
+
repair(options?: Pick<JobRunOptions, 'reporter'>): Promise<boolean>;
|
|
140
|
+
/** The jobs the contract no longer declares whose lease a crashed run still holds: `take` reaps them. */
|
|
141
|
+
orphans(): Promise<readonly string[]>;
|
|
142
|
+
/** How long until every wake due within `withinMs` of the database's clock is due; 0 when none is early. */
|
|
143
|
+
earlyBy(withinMs: number): Promise<number>;
|
|
144
|
+
/**
|
|
145
|
+
* Reaps a crashed holder of `job`'s lease, then, when one of its wakes is due, takes the lease, or sets the pending
|
|
146
|
+
* flag for the run holding it; of a job no longer declared (an orphan), only reaps. Statements only, for the caller's
|
|
147
|
+
* one transaction.
|
|
148
|
+
*/
|
|
149
|
+
take(job: string): Promise<TakenLease>;
|
|
150
|
+
/** Runs `job` under the lease `take` took. A failed run retries the wakes it owns durably. */
|
|
151
|
+
run(job: string, fence: LeaseFence, options?: JobRunOptions): Promise<JobRunResult>;
|
|
152
|
+
/** Reports the crashed run `take` reaped. */
|
|
153
|
+
crashed(job: string, options?: Pick<JobRunOptions, 'reporter'>): Promise<void>;
|
|
154
|
+
/** When the scheduler wakes next: `JobWakes.next`, read in `using` when given. */
|
|
155
|
+
next(using?: Session): Promise<Date | null>;
|
|
156
|
+
/** How far the next wake is from the database's now, in milliseconds: `JobWakes.untilNext`, read in `using` when given. */
|
|
157
|
+
untilNext(using?: Session): Promise<number | null>;
|
|
158
|
+
/** Reports a failure of the scheduler itself: the alarm's or the repair's. Never rejects. */
|
|
159
|
+
failed(step: 'alarm' | 'repair', error: unknown): Promise<void>;
|
|
160
|
+
}
|
|
161
|
+
/** A run that cannot start: an unknown job. Its message is framework-authored. */
|
|
162
|
+
export declare class JobError extends Error {
|
|
163
|
+
readonly name = "JobError";
|
|
164
|
+
}
|
|
165
|
+
export declare const systemClock: JobClock;
|
|
166
|
+
export interface JobBindingInput {
|
|
167
|
+
readonly artifact: ContractArtifact;
|
|
168
|
+
/** The handler tree `boot` binds; a job's handler is `handlers.jobs.<name>`. */
|
|
169
|
+
readonly handlers: unknown;
|
|
170
|
+
readonly database: ContractDatabase | null;
|
|
171
|
+
/** The framework side of `@fabrika/db`, bound by `boot`; `null` when the application has no such layer. */
|
|
172
|
+
readonly framework: FrameworkTables | null;
|
|
173
|
+
readonly ownedDimensions: ReadonlySet<string>;
|
|
174
|
+
/** Where failures and missed runs go: Operations, or the server log without a DSN. */
|
|
175
|
+
readonly reporter: OperationsReporter;
|
|
176
|
+
/** `job:<name>` → the job's key; `boot` refuses a job without one. */
|
|
177
|
+
readonly credentials: ReadonlyMap<string, WorkloadCredential>;
|
|
178
|
+
/** The runtime's capability mint, which `boot` alone holds. */
|
|
179
|
+
readonly mint: CapabilityMint;
|
|
180
|
+
/** The mini-ORM of the bound `scoped(tables)` layer, behind a staged-kit job's `ctx.db`. */
|
|
181
|
+
readonly data: DataAccess | null;
|
|
182
|
+
/** The contract's file kinds, behind a staged-kit job's `ctx.files.put` and `.open`; `null` without any. */
|
|
183
|
+
readonly fileKinds?: StoredFileKinds | null;
|
|
184
|
+
/** The framework's own jobs this contract needs: the scan of its `scan: true` file kinds, and the file sweep. */
|
|
185
|
+
readonly frameworkJobs?: readonly FrameworkJob[];
|
|
186
|
+
/** IAM's membership operations, which a job that `issues` links asks; `null` when the adapter supplies none. */
|
|
187
|
+
readonly membership: IamMembership | null;
|
|
188
|
+
/** The runtime's authority, which a `Ref` passed to IAM must resolve with. */
|
|
189
|
+
readonly capabilities: CapabilityAuthority;
|
|
190
|
+
/** Each dimension's containers, nearest first: a link's chain. */
|
|
191
|
+
readonly containers: ReadonlyMap<string, readonly string[]>;
|
|
192
|
+
/** What a job attempt threw, for the author's own run; without it the error is only its fixed code. */
|
|
193
|
+
readonly revealHandlerErrors?: HandlerErrorSink;
|
|
194
|
+
/** The transports of the jobs that declare `mailer`, which `boot` resolved. */
|
|
195
|
+
readonly mail: MailTransports;
|
|
196
|
+
/** The environment's signed tokens, which a job that declares `signs` signs with. */
|
|
197
|
+
readonly tokens?: SignedTokens;
|
|
198
|
+
/** `ctx.url`: absolute links to the application's own procedures; without it every link is refused. */
|
|
199
|
+
readonly url?: AppUrl;
|
|
200
|
+
}
|
|
201
|
+
export interface BoundJobs {
|
|
202
|
+
readonly jobs: ContractJobs;
|
|
203
|
+
/** The handler ids the jobs took (`jobs.<name>`), so `boot` finds no undeclared handler among them. */
|
|
204
|
+
readonly declared: readonly string[];
|
|
205
|
+
/**
|
|
206
|
+
* Kicks the contract job `name`, as a site's `ctx.kick` does after its commit: a run under the job's own key
|
|
207
|
+
* now, or the shared pending flag for the run holding the lease, which then runs once more after it succeeded. It
|
|
208
|
+
* waits for no lock, settles when that work has ended and never rejects; the schedule stays the recovery path.
|
|
209
|
+
*/
|
|
210
|
+
readonly kick: (name: string) => Promise<void>;
|
|
211
|
+
/**
|
|
212
|
+
* Aborts every kicked run in flight; a later kick starts none and only sets the pending flag, for a process that is
|
|
213
|
+
* not stopping; the schedule recovers their work.
|
|
214
|
+
*/
|
|
215
|
+
readonly stopKicks: () => void;
|
|
216
|
+
}
|
|
217
|
+
/** Binds every declared job to its handler, or adds why it cannot run to `problems`. */
|
|
218
|
+
export declare function bindJobs(input: JobBindingInput, problems: string[]): BoundJobs;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
export interface CronSchedule {
|
|
2
|
+
readonly minutes: ReadonlySet<number>;
|
|
3
|
+
readonly hours: ReadonlySet<number>;
|
|
4
|
+
readonly daysOfMonth: ReadonlySet<number>;
|
|
5
|
+
readonly months: ReadonlySet<number>;
|
|
6
|
+
readonly daysOfWeek: ReadonlySet<number>;
|
|
7
|
+
/** Both day fields name days: a day is due when either matches (Vixie cron). */
|
|
8
|
+
readonly eitherDay: boolean;
|
|
9
|
+
}
|
|
10
|
+
/** The schedule of a five-field expression, or `null` when it is not one this runner reads. */
|
|
11
|
+
export declare function parseCron(expression: string): CronSchedule | null;
|
|
12
|
+
/** Whether the schedule is due in the UTC minute that holds `at`: what a Worker's minute tick runs (ADR-0065). */
|
|
13
|
+
export declare function isDueAt(schedule: CronSchedule, at: Date): boolean;
|
|
14
|
+
/** The latest `count` due minutes at or before `at`, newest first; fewer when the schedule is that rare. */
|
|
15
|
+
export declare function previousDue(schedule: CronSchedule, at: Date, count: number): Date[];
|
|
16
|
+
/** The time between the two latest due minutes at or before `at`, or `null` when there are not two in the window. */
|
|
17
|
+
export declare function periodAt(schedule: CronSchedule, at: Date): number | null;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { CapturedEnvironment } from '../implement/environment';
|
|
2
|
+
export declare const REDACTED = "[redacted]";
|
|
3
|
+
/** A shorter value is no credential the platform generates, and scrubbing it would mangle ordinary text. */
|
|
4
|
+
export declare const MIN_SECRET_LENGTH = 8;
|
|
5
|
+
export interface Scrubber {
|
|
6
|
+
scrub(text: string): string;
|
|
7
|
+
}
|
|
8
|
+
/** Every value of `environment` that is a secret, with the user and password of a URL-shaped one. */
|
|
9
|
+
export declare function secretValues(environment: CapturedEnvironment): string[];
|
|
10
|
+
export declare function secretScrubber(secrets: readonly string[]): Scrubber;
|
|
11
|
+
/** The scrubber of one application environment: its secrets' values, then the credential patterns. */
|
|
12
|
+
export declare function environmentScrubber(environment: CapturedEnvironment): Scrubber;
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import type { EmailDeliveryResult, EmailSenderCapabilities } from '@fabrika/email';
|
|
2
|
+
import type { CronJob, DimensionOf } from '../contract/define';
|
|
3
|
+
import type { FileRef } from '../contract/file';
|
|
4
|
+
import type { AppCapability, Ref, Within } from '../implement/capability';
|
|
5
|
+
import type { AppUrl } from '../implement/urls';
|
|
6
|
+
/** Who a job's writes are stamped with (`createdBy`): the job itself, never a person. */
|
|
7
|
+
export interface JobPrincipal {
|
|
8
|
+
readonly kind: 'job';
|
|
9
|
+
/** `job:<name>`. */
|
|
10
|
+
readonly id: string;
|
|
11
|
+
readonly job: string;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* What a job handler gets. A capability is minted for a declared action only when the token IAM signed for the job's
|
|
15
|
+
* key at the start of the attempt carries it, with the job's `scope: 'app'`, and only while this attempt holds the
|
|
16
|
+
* job's lease: a capability of another attempt is refused, and so is every write after the attempt timed out or lost
|
|
17
|
+
* the lease.
|
|
18
|
+
*/
|
|
19
|
+
export interface JobContext<A extends string, D extends string> {
|
|
20
|
+
readonly principal: JobPrincipal;
|
|
21
|
+
/** This attempt's id; it is also the holder of the job's lease. */
|
|
22
|
+
readonly runId: string;
|
|
23
|
+
/** 1 for the first attempt, one more for each retry. */
|
|
24
|
+
readonly attempt: number;
|
|
25
|
+
/** Aborted when the attempt times out or loses its lease. */
|
|
26
|
+
readonly signal: AbortSignal;
|
|
27
|
+
/** Every value of `dimension`, for a declared action: what a list or an aggregate takes. */
|
|
28
|
+
within<const Act extends A, const Dim extends D>(action: Act, dimension: Dim): Within<Dim, Act>;
|
|
29
|
+
/** One object of `dimension` for a declared action, located now: what a write takes. A missing object is NotFound. */
|
|
30
|
+
ref<const Act extends A, const Dim extends D>(action: Act, dimension: Dim, id: string): Promise<Ref<Dim, Act>>;
|
|
31
|
+
/** A declared action, application-wide: what `ctx.db.app('<action>')` reads and writes the application tables with. */
|
|
32
|
+
app<const Act extends A>(action: Act): AppCapability<Act>;
|
|
33
|
+
/** An absolute link to a procedure of this application: `ctx.url('api.mail.unsubscribe', { query: { t } })`. */
|
|
34
|
+
readonly url: AppUrl;
|
|
35
|
+
}
|
|
36
|
+
/** One message a job sends. The framework prefixes `idempotencyKey` before the transport sees it. */
|
|
37
|
+
export interface AppMailMessage {
|
|
38
|
+
readonly to: string;
|
|
39
|
+
readonly subject: string;
|
|
40
|
+
readonly text: string;
|
|
41
|
+
readonly html?: string;
|
|
42
|
+
/** 1..200 visible ASCII characters, unique per message within this application environment. */
|
|
43
|
+
readonly idempotencyKey: string;
|
|
44
|
+
readonly replyTo?: string;
|
|
45
|
+
readonly fromName?: string;
|
|
46
|
+
/**
|
|
47
|
+
* A one-click unsubscribe (RFC 8058): the transport writes `List-Unsubscribe` and `List-Unsubscribe-Post`. `url` is
|
|
48
|
+
* an `https:` link, usually `ctx.url` of a public procedure that verifies a signed token.
|
|
49
|
+
*/
|
|
50
|
+
readonly unsubscribe?: {
|
|
51
|
+
readonly url: string;
|
|
52
|
+
};
|
|
53
|
+
/**
|
|
54
|
+
* One message of a send to many recipients (a newsletter, an announcement), not a reply to what the recipient did.
|
|
55
|
+
* The transport sends it on the provider's channel for broadcast mail, which keeps it apart from sign-in links and
|
|
56
|
+
* receipts. It needs `unsubscribe`. A transport without `capabilities.broadcast` refuses it as `invalid_message`.
|
|
57
|
+
*/
|
|
58
|
+
readonly broadcast?: boolean;
|
|
59
|
+
/**
|
|
60
|
+
* Files the message carries: references this attempt holds and may read, as `ctx.files.open` takes them. Only a
|
|
61
|
+
* `live` file is sent; the bytes of all of them together stay within the transport's `maxAttachmentBytes`, and a
|
|
62
|
+
* transport without it refuses the message. The idempotency key covers the attachments.
|
|
63
|
+
*/
|
|
64
|
+
readonly attachments?: readonly FileRef[];
|
|
65
|
+
}
|
|
66
|
+
/** `ctx.mail` of a job that declares `mailer`. */
|
|
67
|
+
export interface AppMail {
|
|
68
|
+
/**
|
|
69
|
+
* false where the installation has no mail transport (`FABRIKA_EMAIL_PROVIDER=none`, or a local one without any):
|
|
70
|
+
* every `send` fails `mail_not_configured`, outcome `not_sent`. An outbox then leaves its rows queued and spends no
|
|
71
|
+
* attempt; they leave on the first run after the operator adds a transport and the application is deployed again.
|
|
72
|
+
*/
|
|
73
|
+
readonly available: boolean;
|
|
74
|
+
/** What the transport promises: whether a repeat under one key is deduplicated, sync or queued acceptance. */
|
|
75
|
+
readonly capabilities: EmailSenderCapabilities;
|
|
76
|
+
/**
|
|
77
|
+
* Hands one message to the transport. Rejects with `EmailDeliveryError`; its `outcome` says whether the message may
|
|
78
|
+
* have left. `signal` adds to the attempt's own `ctx.signal`, which always aborts the send.
|
|
79
|
+
*/
|
|
80
|
+
send(message: AppMailMessage, signal?: AbortSignal): Promise<EmailDeliveryResult>;
|
|
81
|
+
/** `mayRetryDelivery` over this transport: true only for an `EmailDeliveryError` that is safe to send again. */
|
|
82
|
+
mayRetry(error: unknown): boolean;
|
|
83
|
+
}
|
|
84
|
+
export type JobHandler<A extends string, D extends string> = (args: {
|
|
85
|
+
readonly ctx: JobContext<A, D>;
|
|
86
|
+
}) => void | Promise<void>;
|
|
87
|
+
type JobsOf<C> = C extends {
|
|
88
|
+
readonly surface: {
|
|
89
|
+
readonly jobs: infer J;
|
|
90
|
+
};
|
|
91
|
+
} ? J : never;
|
|
92
|
+
/** `{ jobs: { <name>: handler } }` for a contract that declares jobs, and nothing for one that declares none. */
|
|
93
|
+
export type JobHandlersOf<C> = [JobsOf<C>] extends [never] ? unknown : {
|
|
94
|
+
readonly jobs: {
|
|
95
|
+
readonly [K in keyof JobsOf<C>]: JobsOf<C>[K] extends CronJob<infer A> ? JobHandler<A, DimensionOf<C>> : never;
|
|
96
|
+
};
|
|
97
|
+
};
|
|
98
|
+
export {};
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import { type ReactNode } from 'react';
|
|
2
|
+
import type { PageCaller } from '../client/caller';
|
|
3
|
+
/** A scope value as the token names it: `{ type: 'org', value: 'acme' }`. */
|
|
4
|
+
export interface CallerScope {
|
|
5
|
+
readonly type: string;
|
|
6
|
+
readonly value: string;
|
|
7
|
+
}
|
|
8
|
+
export interface Caller {
|
|
9
|
+
readonly label: string;
|
|
10
|
+
readonly email: string;
|
|
11
|
+
/**
|
|
12
|
+
* Whether the token grants `action`: without `scope`, app-wide or in any scope value; with `scope`, app-wide or in
|
|
13
|
+
* that value itself. A grant on a container is not seen from a value inside it (the page knows no chain): ask at
|
|
14
|
+
* the dimension the person holds the role in.
|
|
15
|
+
*/
|
|
16
|
+
can(action: string, scope?: CallerScope): boolean;
|
|
17
|
+
}
|
|
18
|
+
/** The caller of a parsed document; exported for a page that reads the document itself. */
|
|
19
|
+
export declare function callerOf(document: PageCaller): Caller;
|
|
20
|
+
/** The page's caller, or `null` while the document loads and when it could not be read (a public SPA answers 401). */
|
|
21
|
+
export declare function useCaller(): Caller | null;
|
|
22
|
+
export interface CanProps {
|
|
23
|
+
readonly action: string;
|
|
24
|
+
readonly scope?: CallerScope;
|
|
25
|
+
/** Shown instead, also while the caller document loads; nothing by default. */
|
|
26
|
+
readonly fallback?: ReactNode;
|
|
27
|
+
readonly children?: ReactNode;
|
|
28
|
+
}
|
|
29
|
+
/** Renders its children when the caller's token grants `action` (see `Caller.can`). Never the access check. */
|
|
30
|
+
export declare function Can({ action, scope, fallback, children }: CanProps): ReactNode;
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
export type FabrikaError = {
|
|
2
|
+
readonly kind: 'unauthenticated';
|
|
3
|
+
readonly message: string;
|
|
4
|
+
/** Where the proxy sends the person to sign in; `null` when the answer carried none. */
|
|
5
|
+
readonly loginUrl: string | null;
|
|
6
|
+
} | {
|
|
7
|
+
readonly kind: 'forbidden';
|
|
8
|
+
readonly message: string;
|
|
9
|
+
} | {
|
|
10
|
+
readonly kind: 'conflict';
|
|
11
|
+
readonly message: string;
|
|
12
|
+
} | {
|
|
13
|
+
readonly kind: 'validation';
|
|
14
|
+
readonly message: string;
|
|
15
|
+
/** The first message for each refused field, by its dotted input path (`title`, `lines.0.amount`). */
|
|
16
|
+
readonly fields: Readonly<Record<string, string>>;
|
|
17
|
+
} | {
|
|
18
|
+
readonly kind: 'not-found';
|
|
19
|
+
readonly message: string;
|
|
20
|
+
} | {
|
|
21
|
+
readonly kind: 'other';
|
|
22
|
+
readonly message: string;
|
|
23
|
+
/** The HTTP status; `0` when the request never got an answer. */
|
|
24
|
+
readonly status: number;
|
|
25
|
+
};
|
|
26
|
+
export type FabrikaErrorKind = FabrikaError['kind'];
|
|
27
|
+
interface Issue {
|
|
28
|
+
readonly path: string;
|
|
29
|
+
readonly message: string;
|
|
30
|
+
}
|
|
31
|
+
/** The first message per path: a field shows one line. */
|
|
32
|
+
export declare function fieldsOf(issues: readonly Issue[]): Readonly<Record<string, string>>;
|
|
33
|
+
/**
|
|
34
|
+
* A refused call as the union, read structurally off the client's `RpcError` (`httpStatus`, `type`, `issues`,
|
|
35
|
+
* `loginUrl`); any other thrown value (a bug in the page) is `other` with status `0`.
|
|
36
|
+
*/
|
|
37
|
+
export declare function toFabrikaError(error: unknown): FabrikaError;
|
|
38
|
+
/** The message for one field of a validation error, or `undefined`: what a form shows under that field. */
|
|
39
|
+
export declare function fieldError(error: FabrikaError | null, path: string): string | undefined;
|
|
40
|
+
export {};
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import { z } from 'zod/v4';
|
|
2
|
+
import type { AttachmentProcedure, DownloadedFile, DownloadInput, FileProcedure } from '../client/contract';
|
|
3
|
+
import type { Schema } from '../contract/define';
|
|
4
|
+
import { type FabrikaError } from './errors';
|
|
5
|
+
import type { InputArgument, InvalidateTarget, PagedProcedure, PageInput, TypedProcedure } from './types';
|
|
6
|
+
/** Pass as the input to wait: the query sends nothing until its input is known. */
|
|
7
|
+
export declare const skip: unique symbol;
|
|
8
|
+
export type QueryState<T> = {
|
|
9
|
+
readonly fetching: boolean;
|
|
10
|
+
refetch(): Promise<void>;
|
|
11
|
+
} & ({
|
|
12
|
+
readonly status: 'idle';
|
|
13
|
+
readonly data: undefined;
|
|
14
|
+
readonly error: null;
|
|
15
|
+
} | {
|
|
16
|
+
readonly status: 'loading';
|
|
17
|
+
readonly data: undefined;
|
|
18
|
+
readonly error: null;
|
|
19
|
+
} | {
|
|
20
|
+
readonly status: 'success';
|
|
21
|
+
readonly data: T;
|
|
22
|
+
readonly error: null;
|
|
23
|
+
}
|
|
24
|
+
/** `data` keeps the last answer when a refetch failed. */
|
|
25
|
+
| {
|
|
26
|
+
readonly status: 'error';
|
|
27
|
+
readonly data: T | undefined;
|
|
28
|
+
readonly error: FabrikaError;
|
|
29
|
+
});
|
|
30
|
+
export interface QueryOptions {
|
|
31
|
+
/**
|
|
32
|
+
* While a new input's answer loads, keep the previous input's answer as `success` data, with `fetching` true: an
|
|
33
|
+
* offset list (`{ items, total }`) whose `limit` or `offset` changes keeps its rows on screen.
|
|
34
|
+
*/
|
|
35
|
+
readonly keepPrevious?: boolean;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* The answer of a query, cached by procedure and input: every view of one call shares one request, and a mutation
|
|
39
|
+
* that invalidates it refetches it. Pass `skip` as the input to wait for a value the input needs.
|
|
40
|
+
*/
|
|
41
|
+
export declare function useQuery<O extends Schema>(procedure: TypedProcedure<Record<never, never> | undefined, O>, input?: typeof skip): QueryState<z.output<O>>;
|
|
42
|
+
export declare function useQuery<I, O extends Schema>(procedure: TypedProcedure<I, O>, input: I | typeof skip, options?: QueryOptions): QueryState<z.output<O>>;
|
|
43
|
+
export interface InfiniteQueryOptions {
|
|
44
|
+
/** How many pages the first load reads: `1` (the default) or every page (`'all'`, for a picker's options). */
|
|
45
|
+
readonly pages?: number | 'all';
|
|
46
|
+
}
|
|
47
|
+
export interface InfiniteQueryState<Item> {
|
|
48
|
+
readonly status: 'idle' | 'loading' | 'success' | 'error';
|
|
49
|
+
/** Every item of the loaded pages, in order. */
|
|
50
|
+
readonly items: readonly Item[];
|
|
51
|
+
readonly error: FabrikaError | null;
|
|
52
|
+
readonly hasMore: boolean;
|
|
53
|
+
readonly fetching: boolean;
|
|
54
|
+
readonly loadingMore: boolean;
|
|
55
|
+
loadMore(): Promise<void>;
|
|
56
|
+
refetch(): Promise<void>;
|
|
57
|
+
/** After a failed later page, asks for that page again; after a failed first load, loads again. */
|
|
58
|
+
retry(): Promise<void>;
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* A cursor list (`{ items, next }`, input `after`): the loaded pages as one list and `loadMore` for the next page. A
|
|
62
|
+
* refetch reads as many pages as are loaded again, from the first cursor.
|
|
63
|
+
*/
|
|
64
|
+
export declare function useInfiniteQuery<I extends {
|
|
65
|
+
readonly after?: string;
|
|
66
|
+
} | undefined, Item>(procedure: PagedProcedure<I, Item>, input: PageInput<I> | typeof skip, options?: InfiniteQueryOptions): InfiniteQueryState<Item>;
|
|
67
|
+
/** What `useDownload`'s `mutate` takes: the attachment procedure's input, or none. */
|
|
68
|
+
export type DownloadArgument<I> = DownloadInput<I>[0];
|
|
69
|
+
/**
|
|
70
|
+
* The download of an attachment procedure (`api.reports.export`) through the provider's client of its mount, so a test
|
|
71
|
+
* that hands the provider a client over the kit downloads over the kit. `mutate(input)` saves the file in a browser and
|
|
72
|
+
* answers it as `data`; a refusal is the state's `error`, as for `useMutation`. It refetches nothing.
|
|
73
|
+
*/
|
|
74
|
+
export declare function useDownload<I>(procedure: AttachmentProcedure<I> | FileProcedure<I>): MutationState<DownloadArgument<I>, DownloadedFile>;
|
|
75
|
+
export type MutationResult<T> = {
|
|
76
|
+
readonly ok: true;
|
|
77
|
+
readonly data: T;
|
|
78
|
+
} | {
|
|
79
|
+
readonly ok: false;
|
|
80
|
+
readonly error: FabrikaError;
|
|
81
|
+
};
|
|
82
|
+
export interface MutationState<I, T> {
|
|
83
|
+
readonly status: 'idle' | 'pending' | 'success' | 'error';
|
|
84
|
+
readonly pending: boolean;
|
|
85
|
+
readonly data: T | undefined;
|
|
86
|
+
readonly error: FabrikaError | null;
|
|
87
|
+
/** Runs the call; never throws: a refusal is `{ ok: false, error }` and the state's `error`. */
|
|
88
|
+
mutate(input: I): Promise<MutationResult<T>>;
|
|
89
|
+
reset(): void;
|
|
90
|
+
}
|
|
91
|
+
export interface MutationOptions<T> {
|
|
92
|
+
/**
|
|
93
|
+
* What to refetch after a success or a `conflict`: procedures and groups of the client. Without it the procedure's own group
|
|
94
|
+
* (`api.deals` for `api.deals.create`); `[]` refetches nothing.
|
|
95
|
+
*/
|
|
96
|
+
readonly invalidates?: readonly InvalidateTarget[];
|
|
97
|
+
readonly onSuccess?: (data: T) => void;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* A mutation of the client: `mutate(input)` checks the input with the procedure's schema (a refused input is a
|
|
101
|
+
* `validation` error and sends nothing), calls it, and after a success refetches what `invalidates` names.
|
|
102
|
+
*/
|
|
103
|
+
export declare function useMutation<I, O extends Schema>(procedure: TypedProcedure<I, O>, options?: MutationOptions<z.output<O>>): MutationState<InputArgument<I>, z.output<O>>;
|
|
104
|
+
/**
|
|
105
|
+
* A call that is no client procedure yet (a file upload until the client covers file collections), with the same
|
|
106
|
+
* state and error union as a mutation. It refetches only what `invalidates` names.
|
|
107
|
+
*/
|
|
108
|
+
export declare function useAction<I, T>(run: (input: I) => Promise<T>, options?: MutationOptions<T>): MutationState<I, T>;
|
|
109
|
+
/** Refetches every shown query under the procedures or groups given, and forgets the cached rest. */
|
|
110
|
+
export declare function useInvalidate(): (...targets: readonly InvalidateTarget[]) => Promise<void>;
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { type Caller, callerOf, type CallerScope, Can, type CanProps, useCaller } from './caller';
|
|
2
|
+
export { type FabrikaError, type FabrikaErrorKind, fieldError, toFabrikaError } from './errors';
|
|
3
|
+
export { type DownloadArgument, type InfiniteQueryOptions, type InfiniteQueryState, type MutationOptions, type MutationResult, type MutationState, type QueryOptions, type QueryState, skip, useAction, useDownload, useInfiniteQuery, useInvalidate, useMutation, useQuery, } from './hooks';
|
|
4
|
+
export { FabrikaProvider, type FabrikaProviderProps } from './provider';
|
|
5
|
+
export type { ClientGroup, ClientProcedure, InputArgument, InvalidateTarget, PageAnswer, PagedProcedure, PageInput, ProcedureInput, ProcedureResult, TypedProcedure, } from './types';
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { type ReactNode } from 'react';
|
|
2
|
+
import { type PageCaller } from '../client/caller';
|
|
3
|
+
import { type ClientNode, type DownloadedFile } from '../client/contract';
|
|
4
|
+
import { type RpcFetch } from '../client/transport';
|
|
5
|
+
import { type FabrikaError } from './errors';
|
|
6
|
+
import { QueryStore, type StoreTarget } from './store';
|
|
7
|
+
export type CallerState = {
|
|
8
|
+
readonly status: 'loading';
|
|
9
|
+
} | {
|
|
10
|
+
readonly status: 'ready';
|
|
11
|
+
readonly caller: PageCaller;
|
|
12
|
+
} | {
|
|
13
|
+
readonly status: 'error';
|
|
14
|
+
readonly error: FabrikaError;
|
|
15
|
+
};
|
|
16
|
+
/** The caller document, read once per provider when a view first asks for it. */
|
|
17
|
+
export declare class CallerSource {
|
|
18
|
+
#private;
|
|
19
|
+
private readonly url;
|
|
20
|
+
private readonly fetch;
|
|
21
|
+
state: CallerState;
|
|
22
|
+
constructor(url: string, fetch: RpcFetch);
|
|
23
|
+
subscribe(listener: () => void): () => void;
|
|
24
|
+
}
|
|
25
|
+
export interface Fabrika {
|
|
26
|
+
readonly store: QueryStore;
|
|
27
|
+
readonly caller: CallerSource;
|
|
28
|
+
/** The call of `procedure` on the provider's client of its mount. */
|
|
29
|
+
target(procedure: unknown, hook: string): ResolvedProcedure;
|
|
30
|
+
/** The download of attachment `procedure` on the provider's client of its mount. */
|
|
31
|
+
attachment(procedure: unknown, hook: string): (input: unknown) => Promise<DownloadedFile>;
|
|
32
|
+
}
|
|
33
|
+
export interface ResolvedProcedure extends StoreTarget {
|
|
34
|
+
readonly node: ClientNode;
|
|
35
|
+
}
|
|
36
|
+
export interface FabrikaProviderProps {
|
|
37
|
+
/** The clients of the mounts the page calls, as `createClient` made them; read at the first render. */
|
|
38
|
+
readonly clients: readonly object[];
|
|
39
|
+
/** The prefix of the SPA mount the page is served from: the caller document is `<spa>/__fabrika-me.json`. */
|
|
40
|
+
readonly spa?: string;
|
|
41
|
+
/**
|
|
42
|
+
* What the caller document, the browser config and the error reports are fetched with; the global `fetch` by default
|
|
43
|
+
* (a test passes the kit's).
|
|
44
|
+
*/
|
|
45
|
+
readonly fetch?: RpcFetch;
|
|
46
|
+
/**
|
|
47
|
+
* Report the page's uncaught errors and unhandled rejections to Operations, through the DSN and release the mount
|
|
48
|
+
* serves at `<spa>/__fabrika-config.json`; `true` by default. Without a DSN nothing is reported.
|
|
49
|
+
*/
|
|
50
|
+
readonly reportErrors?: boolean;
|
|
51
|
+
readonly children?: ReactNode;
|
|
52
|
+
}
|
|
53
|
+
export declare function FabrikaProvider({ clients, spa, fetch: fetchGiven, reportErrors, children }: FabrikaProviderProps): ReactNode;
|
|
54
|
+
export declare function useFabrika(hook: string): Fabrika;
|
|
55
|
+
/** The prefix a mutation invalidates by default: the group it lies in (`api.deals` for `api.deals.create`). */
|
|
56
|
+
export declare function parentOf(node: ClientNode): string;
|
|
57
|
+
/** The prefix of a procedure or a group, for `invalidate`. */
|
|
58
|
+
export declare function prefixOf(target: unknown): string;
|