@keystrokehq/keystroke 1.0.14 → 1.0.17

package/dist/trigger.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_dist = require("./dist-Zh8nB_45.cjs");
+const require_dist = require("./dist-sGyB6KsC.cjs");
 let zod = require("zod");
 //#region ../../node_modules/.pnpm/cron-schedule@6.0.0/node_modules/cron-schedule/dist/utils.js
 function extractDateElements(date) {
@@ -439,8 +439,21 @@ const zodSchema = zod.z.custom((v) => v instanceof zod.z.ZodType, "must be a Zod
 const workflowSchema = zod.z.custom((v) => require_dist.isWorkflow(v), "must be defineWorkflow(...)");
 const agentSchema = zod.z.custom((v) => typeof v === "object" && v !== null && typeof v.slug === "string" && v.slug.trim().length > 0 && typeof v.prompt === "function", "must be defineAgent(...)");
 const promptSchema = zod.z.union([zod.z.string(), zod.z.function()]);
+/** backwards-compat: normalize legacy `key` fields to canonical `slug` before validation. */
+function normalizeLegacySlugFields(value) {
+	if (typeof value !== "object" || value === null) return value;
+	const next = { ...value };
+	if (typeof next.slug !== "string" && typeof next.key === "string") next.slug = next.key;
+	delete next.key;
+	if (typeof next.source === "object" && next.source !== null) next.source = normalizeLegacySlugFields(next.source);
+	return next;
+}
+const slugField = zod.z.string().trim().min(1);
+const optionalTextField = zod.z.string().optional();
 const baseSourceShape = {
-	key: zod.z.string().trim().min(1),
+	slug: slugField,
+	name: optionalTextField,
+	description: optionalTextField,
 	attach: zod.z.function()
 };
 const webhookSourceSchema = zod.z.object({
@@ -466,27 +479,32 @@ const pollSourceSchema = zod.z.object({
 	passes: zod.z.function()
 });
 /** Runtime validation for a trigger source (webhook | cron | poll). */
-const triggerSourceSchema = zod.z.discriminatedUnion("kind", [
+const triggerSourceSchema = zod.z.preprocess(normalizeLegacySlugFields, zod.z.discriminatedUnion("kind", [
 	webhookSourceSchema,
 	cronSourceSchema,
 	pollSourceSchema
-]);
+]));
 const workflowAttachmentSchema = zod.z.object({
-	key: zod.z.string().trim().min(1),
+	slug: slugField,
+	name: optionalTextField,
+	description: optionalTextField,
 	source: triggerSourceSchema,
 	target: zod.z.literal("workflow"),
 	workflow: workflowSchema,
 	transform: zod.z.function().optional()
 });
 const agentAttachmentSchema = zod.z.object({
-	key: zod.z.string().trim().min(1),
+	slug: slugField,
+	name: optionalTextField,
+	description: optionalTextField,
 	source: triggerSourceSchema,
 	target: zod.z.literal("agent"),
 	agent: agentSchema,
 	prompt: promptSchema
 });
+const triggerAttachmentCoreSchemaBase = zod.z.discriminatedUnion("target", [workflowAttachmentSchema, agentAttachmentSchema]);
 /** Runtime validation for an unbranded trigger attachment. */
-const triggerAttachmentCoreSchema = zod.z.discriminatedUnion("target", [workflowAttachmentSchema, agentAttachmentSchema]);
+const triggerAttachmentCoreSchema = zod.z.preprocess(normalizeLegacySlugFields, triggerAttachmentCoreSchemaBase);
 const TRIGGER_ATTACHMENT = Symbol.for("keystroke.triggerAttachment");
 /**
 * Validates brand + shape via `triggerAttachmentCoreSchema` so server discovery
@@ -503,19 +521,54 @@ function isWorkflowTriggerAttachment(attachment) {
 function isAgentTriggerAttachment(attachment) {
 	return attachment.target === "agent";
 }
-function workflowKeyFromDefinition(workflow) {
+/** Resolve slug from authoring options (`slug` preferred, `key` fallback). */
+function resolveAuthoringSlug(input, label = "trigger") {
+	const slug = input.slug?.trim() || input.key?.trim();
+	if (!slug) throw new Error(`${label} requires a non-empty slug`);
+	return slug;
+}
+/** Composite attachment slug `{sourceSlug}:{targetSlug}`. */
+function attachmentSlugFrom(sourceSlug, targetSlug) {
+	return `${sourceSlug}:${targetSlug}`;
+}
+/** Read slug from a trigger source (`slug` preferred, legacy `key` fallback). */
+function sourceSlugFrom(source) {
+	const slug = source.slug?.trim() || source.key?.trim();
+	if (!slug) throw new Error("Trigger source requires slug or legacy key");
+	return slug;
+}
+/** Read slug from a trigger attachment (`slug` preferred, legacy `key` fallback). */
+function attachmentSlugFromRecord(attachment) {
+	const slug = attachment.slug?.trim() || attachment.key?.trim();
+	if (!slug) throw new Error("Trigger attachment requires slug or legacy key");
+	return slug;
+}
+/** Source slug prefix from a composite attachment slug. */
+function triggerSourceSlugFromAttachmentSlug(attachmentSlug) {
+	const separator = attachmentSlug.indexOf(":");
+	return separator === -1 ? attachmentSlug : attachmentSlug.slice(0, separator);
+}
+/** Target slug suffix from a composite attachment slug. */
+function triggerTargetSlugFromAttachmentSlug(attachmentSlug) {
+	const separator = attachmentSlug.indexOf(":");
+	return separator === -1 ? attachmentSlug : attachmentSlug.slice(separator + 1);
+}
+function workflowSlugFromDefinition(workflow) {
 	const slug = workflow.slug?.trim();
 	if (!slug) throw new Error("Workflow definition requires a non-empty slug");
 	return slug;
 }
-function agentKeyFromAgent(agent) {
+function agentSlugFromAgent(agent) {
 	const slug = agent.slug?.trim();
 	if (!slug) throw new Error("Agent definition requires a non-empty slug");
 	return slug;
 }
-function attachmentKeyFrom(triggerKey, targetKey) {
-	return `${triggerKey}:${targetKey}`;
-}
+/** @deprecated Use {@link attachmentSlugFrom}. */
+const attachmentKeyFrom = attachmentSlugFrom;
+/** @deprecated Use {@link workflowSlugFromDefinition}. */
+const workflowKeyFromDefinition = workflowSlugFromDefinition;
+/** @deprecated Use {@link agentSlugFromAgent}. */
+const agentKeyFromAgent = agentSlugFromAgent;
 function isAgentAttachOptions(options) {
 	return "agent" in options;
 }
@@ -528,7 +581,7 @@ function defineTriggerAttachment(input) {
 	const result = triggerAttachmentCoreSchema.safeParse(input);
 	if (!result.success) throw new Error(`Invalid trigger attachment: ${formatIssues(result.error.issues)}`);
 	return {
-		...input,
+		...result.data,
 		[TRIGGER_ATTACHMENT]: true
 	};
 }
@@ -537,16 +590,40 @@ function formatIssues(issues) {
 		return `${issue.path.length > 0 ? `${issue.path.join(".")}: ` : ""}${issue.message}`;
 	}).join("; ");
 }
-function attachFromSource(source, triggerKey, options) {
+function triggerMetaFromSource(source) {
+	return {
+		...source.name !== void 0 ? { name: source.name } : {},
+		...source.description !== void 0 ? { description: source.description } : {}
+	};
+}
+function triggerMetaFromAttachment(attachment) {
+	const name = attachment.name ?? attachment.source.name;
+	const description = attachment.description ?? attachment.source.description;
+	return {
+		...name !== void 0 ? { name } : {},
+		...description !== void 0 ? { description } : {}
+	};
+}
+function triggerMetaRecordFromAttachment(attachment) {
+	const meta = triggerMetaFromAttachment(attachment);
+	return {
+		name: meta.name ?? null,
+		description: meta.description ?? null
+	};
+}
+function attachFromSource(source, sourceSlug, options) {
+	const meta = triggerMetaFromSource(source);
 	if (isAgentAttachOptions(options)) return defineTriggerAttachment({
-		key: attachmentKeyFrom(triggerKey, agentKeyFromAgent(options.agent)),
+		slug: attachmentSlugFrom(sourceSlug, agentSlugFromAgent(options.agent)),
+		...meta,
 		source,
 		target: "agent",
 		agent: options.agent,
 		prompt: options.prompt
 	});
 	return defineTriggerAttachment({
-		key: attachmentKeyFrom(triggerKey, workflowKeyFromDefinition(options.workflow)),
+		slug: attachmentSlugFrom(sourceSlug, workflowSlugFromDefinition(options.workflow)),
+		...meta,
 		source,
 		target: "workflow",
 		workflow: options.workflow,
@@ -569,7 +646,7 @@ function matchWebhookPayload(raw, schemas) {
 		const data = matchShapeAndFilter(zod.z.fromJSONSchema(schema.requestSchema), schema.filterSchema ? zod.z.fromJSONSchema(schema.filterSchema) : void 0, raw);
 		if (data === void 0) continue;
 		matches.push({
-			attachmentKey: schema.attachmentKey,
+			attachmentSlug: schema.attachmentSlug,
 			data
 		});
 	}
@@ -590,19 +667,21 @@ function webhookObjectSchema(schema) {
 * Defines a webhook trigger source — fires its attached workflow when a request
 * hits `/triggers/{endpoint}` and satisfies `request` plus any optional `filter`.
 *
-* @param options.key - Stable trigger key; attachment id is `{key}:{workflowKey}`.
+* @param options.slug - Stable trigger source slug; attachment slug is `{slug}:{targetSlug}`.
+* @param options.key - **Deprecated.** Accepted for backwards-compatible definitions.
 * @param options.endpoint - Shared route suffix under `/triggers/` (e.g. `"stripe"`).
 */
 function defineWebhookSource(options) {
-	const triggerKey = options.key.trim();
-	if (!triggerKey) throw new Error("defineWebhookSource requires a non-empty key");
+	const sourceSlug = resolveAuthoringSlug(options, "defineWebhookSource");
 	const endpoint = normalizeWebhookEndpoint(options.endpoint);
 	if (!endpoint) throw new Error("defineWebhookSource requires a non-empty endpoint");
 	const request = webhookObjectSchema(options.request);
 	const filter = options.filter ? webhookObjectSchema(options.filter) : void 0;
 	const source = {
 		kind: "webhook",
-		key: triggerKey,
+		slug: sourceSlug,
+		...options.name !== void 0 ? { name: options.name } : {},
+		...options.description !== void 0 ? { description: options.description } : {},
 		endpoint,
 		request,
 		filter,
@@ -610,7 +689,7 @@ function defineWebhookSource(options) {
 			return passesTriggerMatch(request, filter, payload);
 		},
 		attach(attachOptions) {
-			return attachFromSource(source, triggerKey, attachOptions);
+			return attachFromSource(source, sourceSlug, attachOptions);
 		}
 	};
 	return source;
@@ -618,23 +697,28 @@ function defineWebhookSource(options) {
 /**
 * Defines a cron trigger source — fires its attached workflow on a schedule.
 *
-* @param options.key - Stable trigger key; the attachment id is `{key}:{workflowKey}`.
+* @param options.slug - Stable trigger source slug; attachment slug is `{slug}:{targetSlug}`.
+* @param options.key - **Deprecated.** Accepted for backwards-compatible definitions.
+* @param options.name - Optional human-readable name shown in the platform.
+* @param options.description - Optional short description shown in the platform.
 * @param options.schedule - A cron expression. Pass a 5-field literal (e.g.
 *   `"0 9 * * *"`) for compile-time shape checking, or wrap with
 *   `parseCronSchedule(...)` for 6-field, named (`MON`), or `@daily`-style
 *   schedules. Validated at runtime; throws if the expression is invalid.
 * @example
-* defineCronSource({ key: "morning", schedule: "0 9 * * *" }).attach({ workflow });
+* defineCronSource({ slug: "morning", schedule: "0 9 * * *" }).attach({ workflow });
 */
 function defineCronSource(options) {
-	const triggerKey = options.key.trim();
-	if (!triggerKey) throw new Error("defineCronSource requires a non-empty key");
+	const sourceSlug = resolveAuthoringSlug(options, "defineCronSource");
+	const schedule = parseCronSchedule(options.schedule);
 	const source = {
 		kind: "cron",
-		key: triggerKey,
-		schedule: parseCronSchedule(options.schedule),
+		slug: sourceSlug,
+		...options.name !== void 0 ? { name: options.name } : {},
+		...options.description !== void 0 ? { description: options.description } : {},
+		schedule,
 		attach(attachOptions) {
-			return attachFromSource(source, triggerKey, attachOptions);
+			return attachFromSource(source, sourceSlug, attachOptions);
 		}
 	};
 	return source;
@@ -643,25 +727,27 @@ function defineCronSource(options) {
 * Defines a poll trigger source — runs `run` on a schedule and, when the result
 * passes any `.filter(...)`, fires the attached workflow with it.
 *
-* @param options.key - Stable trigger key; the attachment id is `{key}:{workflowKey}`.
+* @param options.slug - Stable trigger source slug; attachment slug is `{slug}:{targetSlug}`.
+* @param options.key - **Deprecated.** Accepted for backwards-compatible definitions.
 * @param options.id - Optional group id; poll sources sharing an id poll together.
 * @param options.schedule - Cron expression for the poll cadence (see `defineCronSource`).
 * @param options.run - Produces the payload checked by `filter` and passed to the workflow.
 * @param options.filter - Source-level predicate; the workflow only fires when it returns true.
 * @example
-* definePollSource({ key: "inbox", schedule: "0 * * * *", run: fetchInbox })
+* definePollSource({ slug: "inbox", schedule: "0 * * * *", run: fetchInbox })
 *   .filter((r) => r.length > 0)
 *   .attach({ workflow });
 */
 function definePollSource(options) {
-	const triggerKey = options.key.trim();
-	if (!triggerKey) throw new Error("definePollSource requires a non-empty key");
+	const sourceSlug = resolveAuthoringSlug(options, "definePollSource");
 	const schedule = parseCronSchedule(options.schedule);
 	const filters = [];
 	if (options.filter) filters.push(options.filter);
 	const source = {
 		kind: "poll",
-		key: triggerKey,
+		slug: sourceSlug,
+		...options.name !== void 0 ? { name: options.name } : {},
+		...options.description !== void 0 ? { description: options.description } : {},
 		id: options.id,
 		schedule,
 		run: options.run,
@@ -670,7 +756,7 @@ function definePollSource(options) {
 			return source.filters.every((candidate) => candidate(payload));
 		},
 		attach(attachOptions) {
-			return attachFromSource(source, triggerKey, attachOptions);
+			return attachFromSource(source, sourceSlug, attachOptions);
 		}
 	};
 	const chain = source;
@@ -759,6 +845,11 @@ function resolveAttachmentInput(attachment, payload) {
 }
 //#endregion
 exports.TRIGGER_ATTACHMENT = TRIGGER_ATTACHMENT;
+exports.agentKeyFromAgent = agentKeyFromAgent;
+exports.agentSlugFromAgent = agentSlugFromAgent;
+exports.attachmentKeyFrom = attachmentKeyFrom;
+exports.attachmentSlugFrom = attachmentSlugFrom;
+exports.attachmentSlugFromRecord = attachmentSlugFromRecord;
 exports.cronScheduleSchema = cronScheduleSchema;
 exports.defineCronSource = defineCronSource;
 exports.definePollSource = definePollSource;
@@ -776,6 +867,15 @@ exports.parseTriggerSchedule = parseTriggerSchedule;
 exports.resolveAgentPrompt = resolveAgentPrompt;
 exports.resolveAttachmentInput = resolveAttachmentInput;
 exports.resolveAttachmentTransform = resolveAttachmentTransform;
+exports.resolveAuthoringSlug = resolveAuthoringSlug;
 exports.resolveCronSchedule = resolveCronSchedule;
+exports.sourceSlugFrom = sourceSlugFrom;
+exports.triggerMetaFromAttachment = triggerMetaFromAttachment;
+exports.triggerMetaFromSource = triggerMetaFromSource;
+exports.triggerMetaRecordFromAttachment = triggerMetaRecordFromAttachment;
+exports.triggerSourceSlugFromAttachmentSlug = triggerSourceSlugFromAttachmentSlug;
+exports.triggerTargetSlugFromAttachmentSlug = triggerTargetSlugFromAttachmentSlug;
+exports.workflowKeyFromDefinition = workflowKeyFromDefinition;
+exports.workflowSlugFromDefinition = workflowSlugFromDefinition;
 
 //# sourceMappingURL=trigger.cjs.map