feat: forward certificateSettings so a course.json can pick its certificate template

[rryoung98]

Summary of changes

Stacked on #33 (base is feat/course-duration-weeks, not main); merge #33 first.

The same round-trip that dropped durationWeeks also drops certificateSettings: the validate step rewrites the payload through the Course model, and pydantic ignores fields the model does not declare. So an author could not enable certificates or choose a certificate design from course.json; only the qBook admin UI could, after the deploy.

• Course gains an optional certificateSettings with enabled (strict bool), criteria ({type: completion|points, value >= 0}) and templateId (qbraid, quera or qct), mirroring the qBraid API's validator so a typo fails at validation with a field-level message instead of a 400 at deploy time. Both models forbid unknown keys, so templateID fails with an error naming the key instead of being dropped. criteria.value is strict and finite: "80", true, inf and NaN are refused, not coerced.
• Course.to_payload() replaces the bare model_dump at the write site. It omits certificateSettings when absent (and criteria when absent inside it), because the API's schema is optional(object) and refuses an explicit null. durationWeeks keeps its documented null.
• Tests: forwarded verbatim; absent → key omitted; nested absent criteria omitted; QCT, thailand, missing enabled, "yes", grade, negative value, string value, boolean value, inf, NaN all fail validation; an unknown key (templateID, criteria.valu) fails with an extra_forbidden error whose location names that key.

Example course.json addition:

"certificateSettings": {
  "enabled": true,
  "criteria": { "type": "completion", "value": 80 },
  "templateId": "qct"
}

On the API side, POST /learn/articles/course/ingest and PUT /learn/articles/course/:customId already accept this shape; qBraid/qbraid-api#1136 makes the create path persist templateId and preserves a stored template when a redeploy omits it.

Validation run: pytest test (198 passed: 188 unit, 10 e2e), make format-check clean.

Partner designs (quera, qct) need a grant on the course's organization, set by qBraid staff; the deploy domain grants nothing. Without the grant the API answers 403 CERTIFICATE_TEMPLATE_NOT_ALLOWED and the action fails showing that response. A new course with no templateId gets quera only on a quera.com course whose organization holds the quera grant, otherwise qbraid. The README says this.

Coordinated PRs

• feat: forward durationWeeks from course.json to the deploy payload #33 (base of this stack)
• qBraid/qbraid-api#1136 (create path persists templateId; redeploys without one keep the stored value)
• qBraid/course-processor#40 (the qct design)

Deploy a course naming qct only once #1136 and #40 are live on the target environment; before that the API's enum rejects it with a 400 naming the allowed values.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

CertificateCriteria.value currently allows unintended coercions (e.g., booleans / numeric strings) that can let invalid course.json pass validation and fail later at deploy time.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Float field coerces bools and strings into valid criteria values · New

What changed in this PR

This PR extends the Course validation/serialization pipeline so course.json can declare certificateSettings (including certificate enablement criteria and an optional certificate template), and ensures the deploy payload preserves these fields instead of dropping them during the Pydantic model round-trip.

Changes:

• Added CertificateSettings/CertificateCriteria models and a Course.certificateSettings field to validate certificate configuration early.
• Introduced Course.to_payload() and switched the validate step to write course_data.json using it, omitting certificateSettings (and nested criteria) when absent to avoid sending explicit null.
• Added unit tests covering forwarding behavior, omission behavior, and several invalid-shape/invalid-enum validation failures.

File	Description
src/​scripts/​validate_course.py	Adds certificate models and to_payload() to correctly forward/omit certificateSettings in the deploy payload.
test/​unit/​test_validate_course.py	Adds tests ensuring certificateSettings is forwarded and invalid inputs fail validation.
CHANGELOG.md	Documents the new forwarding behavior for certificateSettings.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[rryoung98]

Exercised live through the Action from a qBraid-tutorial workflow (uses: qBraid/upload-course-action@feat/course-certificate-settings, update mode) into a preview API on qbraid-api#1136, reading the course back by id after each run:

• run 35757248347: course.json names templateId: "quera", completion 5 → stored {enabled: true, criteria: {completion, 5}, templateId: quera}.
• run 35757373137: certificateSettings removed from course.json → stored values unchanged (the key is omitted from the payload, and the API's merge keeps the stored template).
• run 35757548917: templateId: "qct", completion 0 → moved back.

durationWeeks (#33) rode through all three redeploys.

[rryoung98]

Exercised live: the Action deployed a new course into a preview of qbraid-api #1093/#1136/#1156, first in create mode and then in update mode.

Checked live, working

• Create mode with certificateSettings: {enabled, criteria, templateId: "qct"} stored all three.

Findings

1. A course.json that sets certificateSettings without criteria erases the criteria an admin stored. Reproduced live: points >= 5 was set through the settings route, then an update-mode deploy with {enabled: true, templateId: "qct"} left the stored settings as {enabled: true, templateId: "qct"}, so issuance falls back to completion 100. The API merge keeps only templateId (qbraid-api #1136, mergeCertificateSettings). Either the API carries criteria over too, or the README should say that omitting criteria resets it.
2. CertificateCriteria.value accepts "inf" and 1e999. json.dump then writes a bare Infinity, and the API rejects the body with 400, which is the late failure validation is meant to prevent. Field(..., ge=0, strict=True, allow_inf_nan=False) fixes it. (Reproduced with pydantic locally.)

[rryoung98]

@avanbussum Ready for review. Changes from the internal pass: certificateSettings and criteria now reject unknown keys (a typo like templateID used to be dropped silently), and criteria.value is strict (9d038c1). The README's quera rules are corrected: a partner design needs an org grant.