@frontera-sdk/functions 1.49.0

package/src/messages.ts

@@ -0,0 +1,108 @@
+/**
+ * Everything an author reads when the platform turns their code away.
+ *
+ * They live in the SDK, not in the runner, because three surfaces have to say
+ * exactly the same sentence: the runner refusing a call before it makes it, the
+ * service refusing it after, and `createTestContext` refusing it on the author's
+ * own machine. Three copies of a message drift, and a test that fails with
+ * different words than production is a test that teaches the wrong lesson.
+ */
+
+/**
+ * A `ctx` call the manifest does not permit.
+ *
+ * Names the fix, not the verdict: the author is looking at CLI output, and
+ * "missing grant" without the remedy costs them a round trip through the docs.
+ */
+export function missingGrantMessage(grant: string): string {
+  return `Automation is missing the "${grant}" grant. Add it to the manifest and redeploy.`
+}
+
+/**
+ * One step name used twice in a run.
+ *
+ * The platform memoizes by name, so the second call would return the FIRST
+ * step's result — no error, no warning, a wrong value flowing on. The remedy
+ * names THIS step rather than a placeholder, because a hint that reads as code
+ * to paste gets pasted.
+ */
+export function duplicateStepMessage(name: string): string {
+  return (
+    `Duplicate automation step name "${name}". Step names must be unique within a run — ` +
+    "the platform memoizes by name, so this call would return the first step's result " +
+    'instead of running again. If this is a loop, add the index: ' +
+    `ctx.step.run(\`${name}:\${i}\`, ...)`
+  )
+}
+
+/**
+ * A submit inside a step whose own row never recorded.
+ *
+ * Recording a step is contractually non-fatal — telemetry must not fail a run —
+ * so the id comes back empty and everything else carries on. A submission
+ * cannot: the row is what the idempotency key is derived from, and improvising
+ * one is how the same effect happens twice. Named here rather than left to the
+ * service's generic invalid-submission, which would blame the payload.
+ */
+export function lostStepRowMessage(stepName: string): string {
+  return (
+    `ctx.action.submit cannot run in step "${stepName}": the step's own record failed to write, ` +
+    'so there is nothing stable to key the submission on and it is refused rather than sent ' +
+    'twice. This is a transient service failure — retry the run.'
+  )
+}
+
+/**
+ * The same Action submitted twice from one step with no way to tell them apart.
+ *
+ * Refused HERE, locally, rather than left to the write plane, because the plane
+ * cannot refuse it: two identical submissions derive one idempotency key AND
+ * one semantic fingerprint, so it replays the first request and answers both
+ * calls with the same request id. Nothing errors, one effect happens, and the
+ * run reports success — the failure mode a batch loop hits on its second row
+ * and not on a one-row fixture.
+ *
+ * Naming the remedy matters more than usual: `submissionKey` is the one field
+ * an author has to reach for to fix this, and it is not guessable from a 409.
+ */
+export function duplicateSubmissionMessage(apiName: string): string {
+  return (
+    `Step already submitted "${apiName}" with the same submissionKey. Two submissions the ` +
+    'platform cannot tell apart become ONE request — the plane replays the first and the second ' +
+    'effect never happens. If this is a batch, give each submission a distinct submissionKey ' +
+    "keyed on what it acts on: ctx.action.submit({ action: '" + apiName + "', submissionKey: " +
+    'row.id, ... }). If it is a retry, it is already idempotent — drop the loop.'
+  )
+}
+
+/**
+ * An empty `submissionKey`.
+ *
+ * Refused rather than treated as absent, and refused in both layers: the
+ * service rejects it by name, so folding it into the no-key identity here
+ * would make the SDK and the service disagree about what the author asked for.
+ */
+export function emptySubmissionKeyMessage(apiName: string): string {
+  return (
+    `ctx.action.submit("${apiName}") was given an empty submissionKey. Omit it entirely to mean ` +
+    '"this step submits once", or pass a value identifying what this submission acts on.'
+  )
+}
+
+/**
+ * `ctx.action.submit` called outside a step.
+ *
+ * States the consequence rather than the rule, because the rule on its own
+ * reads as ceremony: code outside a step runs again after EVERY step the
+ * handler completes, so a submit there is not one submission with a retry
+ * risk — it is one submission per step boundary, every time the run resumes.
+ * The step row is also what the idempotency key is derived from, so there is
+ * nothing to derive one from out here.
+ */
+export function submitOutsideStepMessage(apiName: string): string {
+  return (
+    `ctx.action.submit("${apiName}") must be called inside ctx.step.run. Code outside a step ` +
+    're-executes every time the run resumes, so this would submit once per step boundary. ' +
+    `Wrap it: ctx.step.run('submit-${apiName}', () => ctx.action.submit({ ... }))`
+  )
+}