@lssm/example.saas-boilerplate 0.0.0-canary-20251217060834 → 0.0.0-canary-20251217072406

package/dist/libs/jobs/dist/contracts/index.js

@@ -0,0 +1,484 @@
+import { ScalarTypeEnum } from "../schema/dist/ScalarTypeEnum.js";
+import { defineSchemaModel } from "../schema/dist/SchemaModel.js";
+import "../schema/dist/index.js";
+import { defineCommand, defineQuery } from "./dist/spec.js";
+import "./dist/index.js";
+
+//#region ../../libs/jobs/dist/contracts/index.js
+const OWNERS = ["platform.jobs"];
+const JobModel = defineSchemaModel({
+	name: "Job",
+	description: "Represents a background job",
+	fields: {
+		id: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		type: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		version: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		payload: {
+			type: ScalarTypeEnum.JSON(),
+			isOptional: false
+		},
+		status: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		priority: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		attempts: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		maxRetries: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		createdAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: false
+		},
+		updatedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: false
+		},
+		scheduledAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		startedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		completedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		lastError: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const ScheduledJobModel = defineSchemaModel({
+	name: "ScheduledJob",
+	description: "Represents a scheduled/recurring job",
+	fields: {
+		id: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		name: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		description: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		cronExpression: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		timezone: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		jobType: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		enabled: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: false
+		},
+		lastRunAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		nextRunAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		createdAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: false
+		}
+	}
+});
+const QueueStatsModel = defineSchemaModel({
+	name: "QueueStats",
+	description: "Job queue statistics",
+	fields: {
+		pending: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		running: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		completed: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		failed: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		deadLetter: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		}
+	}
+});
+const EnqueueJobInput = defineSchemaModel({
+	name: "EnqueueJobInput",
+	description: "Input for enqueuing a new job",
+	fields: {
+		type: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		payload: {
+			type: ScalarTypeEnum.JSON(),
+			isOptional: false
+		},
+		delaySeconds: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		dedupeKey: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		maxRetries: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		priority: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		timeoutMs: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const GetJobInput = defineSchemaModel({
+	name: "GetJobInput",
+	description: "Input for getting a job by ID",
+	fields: { jobId: {
+		type: ScalarTypeEnum.String_unsecure(),
+		isOptional: false
+	} }
+});
+const CancelJobInput = defineSchemaModel({
+	name: "CancelJobInput",
+	description: "Input for cancelling a job",
+	fields: { jobId: {
+		type: ScalarTypeEnum.String_unsecure(),
+		isOptional: false
+	} }
+});
+const CancelJobOutput = defineSchemaModel({
+	name: "CancelJobOutput",
+	description: "Output for cancel job operation",
+	fields: { success: {
+		type: ScalarTypeEnum.Boolean(),
+		isOptional: false
+	} }
+});
+const CreateScheduledJobInput = defineSchemaModel({
+	name: "CreateScheduledJobInput",
+	description: "Input for creating a scheduled job",
+	fields: {
+		name: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		description: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		cronExpression: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		timezone: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		jobType: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		payload: {
+			type: ScalarTypeEnum.JSON(),
+			isOptional: true
+		},
+		maxRetries: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		enabled: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		}
+	}
+});
+const ListScheduledJobsOutput = defineSchemaModel({
+	name: "ListScheduledJobsOutput",
+	description: "Output for listing scheduled jobs",
+	fields: { schedules: {
+		type: ScheduledJobModel,
+		isArray: true,
+		isOptional: false
+	} }
+});
+const ToggleScheduledJobInput = defineSchemaModel({
+	name: "ToggleScheduledJobInput",
+	description: "Input for toggling a scheduled job",
+	fields: {
+		name: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		enabled: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: false
+		}
+	}
+});
+const JobEnqueuedPayload = defineSchemaModel({
+	name: "JobEnqueuedPayload",
+	description: "Payload for job.enqueued event",
+	fields: {
+		jobId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		type: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		priority: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		scheduledAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		tenantId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		enqueuedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: false
+		}
+	}
+});
+const JobCancelledPayload = defineSchemaModel({
+	name: "JobCancelledPayload",
+	description: "Payload for job.cancelled event",
+	fields: { jobId: {
+		type: ScalarTypeEnum.String_unsecure(),
+		isOptional: false
+	} }
+});
+/**
+* Enqueue a job.
+*/
+const EnqueueJobContract = defineCommand({
+	meta: {
+		name: "jobs.enqueue",
+		version: 1,
+		stability: "stable",
+		owners: [...OWNERS],
+		tags: ["jobs", "enqueue"],
+		description: "Enqueue a background job for async processing.",
+		goal: "Allow services to offload work to background processing.",
+		context: "Called by any service that needs async processing."
+	},
+	io: {
+		input: EnqueueJobInput,
+		output: JobModel
+	},
+	policy: { auth: "user" },
+	sideEffects: { emits: [{
+		name: "job.enqueued",
+		version: 1,
+		when: "Job is enqueued",
+		payload: JobEnqueuedPayload
+	}] }
+});
+/**
+* Get job by ID.
+*/
+const GetJobContract = defineQuery({
+	meta: {
+		name: "jobs.get",
+		version: 1,
+		stability: "stable",
+		owners: [...OWNERS],
+		tags: ["jobs", "get"],
+		description: "Get a job by ID.",
+		goal: "Check job status and result.",
+		context: "Called to poll job status or retrieve results."
+	},
+	io: {
+		input: GetJobInput,
+		output: JobModel
+	},
+	policy: { auth: "user" }
+});
+/**
+* Cancel a job.
+*/
+const CancelJobContract = defineCommand({
+	meta: {
+		name: "jobs.cancel",
+		version: 1,
+		stability: "stable",
+		owners: [...OWNERS],
+		tags: ["jobs", "cancel"],
+		description: "Cancel a pending job.",
+		goal: "Allow cancellation of jobs that are no longer needed.",
+		context: "Only pending jobs can be cancelled."
+	},
+	io: {
+		input: CancelJobInput,
+		output: CancelJobOutput,
+		errors: {
+			JOB_NOT_FOUND: {
+				description: "Job does not exist",
+				http: 404,
+				gqlCode: "JOB_NOT_FOUND",
+				when: "Job ID is invalid"
+			},
+			JOB_NOT_PENDING: {
+				description: "Job is not in pending state",
+				http: 409,
+				gqlCode: "JOB_NOT_PENDING",
+				when: "Job has already started or completed"
+			}
+		}
+	},
+	policy: { auth: "user" },
+	sideEffects: { emits: [{
+		name: "job.cancelled",
+		version: 1,
+		when: "Job is cancelled",
+		payload: JobCancelledPayload
+	}] }
+});
+/**
+* Get queue statistics.
+*/
+const GetQueueStatsContract = defineQuery({
+	meta: {
+		name: "jobs.stats",
+		version: 1,
+		stability: "stable",
+		owners: [...OWNERS],
+		tags: [
+			"jobs",
+			"stats",
+			"admin"
+		],
+		description: "Get job queue statistics.",
+		goal: "Monitor queue health and backlog.",
+		context: "Admin dashboard monitoring."
+	},
+	io: {
+		input: null,
+		output: QueueStatsModel
+	},
+	policy: { auth: "admin" }
+});
+/**
+* Create a scheduled job.
+*/
+const CreateScheduledJobContract = defineCommand({
+	meta: {
+		name: "jobs.schedule.create",
+		version: 1,
+		stability: "stable",
+		owners: [...OWNERS],
+		tags: [
+			"jobs",
+			"schedule",
+			"create"
+		],
+		description: "Create a scheduled/recurring job.",
+		goal: "Set up recurring background tasks.",
+		context: "Admin configuration for periodic tasks."
+	},
+	io: {
+		input: CreateScheduledJobInput,
+		output: ScheduledJobModel
+	},
+	policy: { auth: "admin" }
+});
+/**
+* List scheduled jobs.
+*/
+const ListScheduledJobsContract = defineQuery({
+	meta: {
+		name: "jobs.schedule.list",
+		version: 1,
+		stability: "stable",
+		owners: [...OWNERS],
+		tags: [
+			"jobs",
+			"schedule",
+			"list"
+		],
+		description: "List all scheduled jobs.",
+		goal: "View configured recurring tasks.",
+		context: "Admin dashboard."
+	},
+	io: {
+		input: null,
+		output: ListScheduledJobsOutput
+	},
+	policy: { auth: "admin" }
+});
+/**
+* Toggle scheduled job enabled state.
+*/
+const ToggleScheduledJobContract = defineCommand({
+	meta: {
+		name: "jobs.schedule.toggle",
+		version: 1,
+		stability: "stable",
+		owners: [...OWNERS],
+		tags: [
+			"jobs",
+			"schedule",
+			"toggle"
+		],
+		description: "Enable or disable a scheduled job.",
+		goal: "Control when recurring tasks run.",
+		context: "Admin control over scheduled tasks."
+	},
+	io: {
+		input: ToggleScheduledJobInput,
+		output: ScheduledJobModel
+	},
+	policy: { auth: "admin" }
+});
+
+//#endregion
+export { JobModel, QueueStatsModel, ScheduledJobModel };

package/dist/libs/jobs/dist/entities/index.js

@@ -0,0 +1,198 @@
+import { defineEntity, defineEntityEnum, field, index } from "../schema/dist/entity/defineEntity.js";
+import "../schema/dist/index.js";
+
+//#region ../../libs/jobs/dist/entities/index.js
+/**
+* Job status enum.
+*/
+const JobStatusEnum = defineEntityEnum({
+	name: "JobStatus",
+	values: [
+		"PENDING",
+		"RUNNING",
+		"COMPLETED",
+		"FAILED",
+		"CANCELLED",
+		"DEAD_LETTER"
+	],
+	schema: "lssm_jobs",
+	description: "Status of a background job."
+});
+/**
+* Job entity - represents a single job execution.
+*/
+const JobEntity = defineEntity({
+	name: "Job",
+	description: "A background job for async processing.",
+	schema: "lssm_jobs",
+	map: "job",
+	fields: {
+		id: field.id({ description: "Unique job identifier" }),
+		type: field.string({ description: "Job type identifier" }),
+		version: field.int({
+			default: 1,
+			description: "Job type version"
+		}),
+		payload: field.json({ description: "Job payload data" }),
+		status: field.enum("JobStatus", { default: "PENDING" }),
+		priority: field.int({
+			default: 0,
+			description: "Higher = more urgent"
+		}),
+		attempts: field.int({
+			default: 0,
+			description: "Number of execution attempts"
+		}),
+		maxRetries: field.int({
+			default: 3,
+			description: "Maximum retry attempts"
+		}),
+		lastError: field.string({
+			isOptional: true,
+			description: "Last error message"
+		}),
+		lastErrorStack: field.string({
+			isOptional: true,
+			description: "Last error stack trace"
+		}),
+		scheduledAt: field.dateTime({
+			isOptional: true,
+			description: "When job should be processed"
+		}),
+		startedAt: field.dateTime({
+			isOptional: true,
+			description: "When processing started"
+		}),
+		completedAt: field.dateTime({
+			isOptional: true,
+			description: "When processing completed"
+		}),
+		timeoutAt: field.dateTime({
+			isOptional: true,
+			description: "Job timeout deadline"
+		}),
+		dedupeKey: field.string({
+			isOptional: true,
+			description: "Key for deduplication"
+		}),
+		tenantId: field.string({
+			isOptional: true,
+			description: "Tenant/org context"
+		}),
+		userId: field.string({
+			isOptional: true,
+			description: "User who enqueued"
+		}),
+		traceId: field.string({
+			isOptional: true,
+			description: "Distributed trace ID"
+		}),
+		metadata: field.json({
+			isOptional: true,
+			description: "Additional metadata"
+		}),
+		result: field.json({
+			isOptional: true,
+			description: "Job result data"
+		}),
+		createdAt: field.createdAt(),
+		updatedAt: field.updatedAt(),
+		scheduledJob: field.belongsTo("ScheduledJob", ["scheduledJobId"], ["id"]),
+		scheduledJobId: field.string({ isOptional: true }),
+		executions: field.hasMany("JobExecution")
+	},
+	indexes: [
+		index.on(["status", "scheduledAt"]),
+		index.on(["type", "status"]),
+		index.on(["tenantId", "status"]),
+		index.unique(["dedupeKey"], { name: "job_dedupe_key_unique" })
+	],
+	enums: [JobStatusEnum]
+});
+/**
+* ScheduledJob entity - recurring job definitions.
+*/
+const ScheduledJobEntity = defineEntity({
+	name: "ScheduledJob",
+	description: "A scheduled/recurring job definition.",
+	schema: "lssm_jobs",
+	map: "scheduled_job",
+	fields: {
+		id: field.id(),
+		name: field.string({
+			isUnique: true,
+			description: "Unique schedule name"
+		}),
+		description: field.string({ isOptional: true }),
+		cronExpression: field.string({ description: "Cron expression for scheduling" }),
+		timezone: field.string({
+			default: "\"UTC\"",
+			description: "Timezone for cron evaluation"
+		}),
+		jobType: field.string({ description: "Job type to create" }),
+		jobVersion: field.int({ default: 1 }),
+		payload: field.json({
+			isOptional: true,
+			description: "Default payload for created jobs"
+		}),
+		maxRetries: field.int({ default: 3 }),
+		timeoutMs: field.int({
+			isOptional: true,
+			description: "Job timeout in milliseconds"
+		}),
+		enabled: field.boolean({ default: true }),
+		lastRunAt: field.dateTime({ isOptional: true }),
+		nextRunAt: field.dateTime({ isOptional: true }),
+		tenantId: field.string({ isOptional: true }),
+		createdAt: field.createdAt(),
+		updatedAt: field.updatedAt(),
+		jobs: field.hasMany("Job")
+	},
+	indexes: [index.on(["enabled", "nextRunAt"])]
+});
+/**
+* JobExecution entity - individual execution attempts.
+*/
+const JobExecutionEntity = defineEntity({
+	name: "JobExecution",
+	description: "A single execution attempt of a job.",
+	schema: "lssm_jobs",
+	map: "job_execution",
+	fields: {
+		id: field.id(),
+		jobId: field.foreignKey(),
+		attemptNumber: field.int({ description: "Which attempt this is" }),
+		startedAt: field.dateTime(),
+		completedAt: field.dateTime({ isOptional: true }),
+		durationMs: field.int({ isOptional: true }),
+		success: field.boolean({ isOptional: true }),
+		error: field.string({ isOptional: true }),
+		errorStack: field.string({ isOptional: true }),
+		result: field.json({ isOptional: true }),
+		workerId: field.string({
+			isOptional: true,
+			description: "ID of worker that processed"
+		}),
+		job: field.belongsTo("Job", ["jobId"], ["id"], { onDelete: "Cascade" })
+	},
+	indexes: [index.on(["jobId", "attemptNumber"])]
+});
+/**
+* All job entities for schema composition.
+*/
+const jobEntities = [
+	JobEntity,
+	ScheduledJobEntity,
+	JobExecutionEntity
+];
+/**
+* Module schema contribution for jobs.
+*/
+const jobsSchemaContribution = {
+	moduleId: "@lssm/lib.jobs",
+	entities: jobEntities,
+	enums: [JobStatusEnum]
+};
+
+//#endregion
+export { JobEntity, JobExecutionEntity, JobStatusEnum, ScheduledJobEntity, jobEntities, jobsSchemaContribution };