Archive Asset

1. Front Matter

Title: Archive Asset
Author: Joshua Uriel Tribiana
Updated by: Christian Denzon (archive overhaul — Trash → Archive rename, 120-day retention, auto-purge and warning crons, archive sort & toolbar consistency; July – September 2026)
Reviewer: Patrick Babala, Clyde Ador
Handover To: Christian
Sprint Target: Week 12
Created: July 2026
Last Updated: September 30, 2026
Status: Approved and Merged
References:

  • Issue: #37 [3.6] Archive Asset

  • Sub-issue: #727 [3.6.1] Bulk Select/Delete/Archive/Restore Quests, Adventures, Background Assets — shipped in PR #728; documented separately in the Bulk Actions Internal Technical Guide (cross-reference, not duplicated here)

  • Implementation PRs:

  • Related: #777 Reusable Confirm-Destructive Modal — typed DELETE confirmation shared with the permanent archive-delete flows

  • Implementation files (current paths):

    • app/api/creator/(background-assets)/delete-assets/route.ts, restore-assets/route.ts, purge-assets/route.ts, get-trash-assets/route.ts, list-assets/route.ts

    • app/api/creator/(content)/archive-content/route.ts, restore-content/route.ts, permanent-delete/route.ts, list-archived/route.ts

    • app/api/cron/check-pending-deletion/route.ts, app/api/cron/purge-expired-archived/route.ts

    • lib/archive/getDaysRemaining.ts, lib/archive/purgeArchivedContent.ts, lib/archive/sortArchivedItems.ts

    • shared/schemas/contentManagementSchema.ts

    • app/creator/archive/page.tsx

    • components/creator/TrashContent.tsx, components/creator/MyContent.tsx, components/creator/SortDropdown.tsx, components/creator/ArchiveSortDropdown.tsx

    • components/creator/background-assets/AssetList.tsx, components/creator/background-assets/DeleteAssetModal.tsx

    • lib/email/templates/AutoDeletionWarningEmail.tsx, lib/email/renderEmail.tsx

    • .github/workflows/cron-pending-deletion.yml, .github/workflows/cron-purge-expired.yml


2. Introduction & Goals

Problem Summary: Creators need a safe way to remove content (quests, adventures) and background assets from active libraries without immediate permanent deletion. Archive Asset implements soft-delete behaviour and routes archived items to a dedicated Archive surface, where they can be restored within a retention window. Since PR #711 the surface is called Archive everywhere in the UI (it was previously “Trash”), the retention window is 120 days for both content and assets (previously 30 days for assets), and a pair of daily scheduled jobs warn creators 30 days before expiry and then permanently purge expired rows.

Goals:

  • Soft-delete content and assets by recording archive metadata instead of hard-deleting immediately.

  • Keep active library listings clean by excluding archived rows.

  • Provide an Archive retrieval path with restore capability.

  • Track retention window data (deleted_at / archived_at, expires_at) and surface a live countdown badge ({days}d left).

  • Notify creators once, 30 days before permanent deletion, with a single grouped email listing every expiring item.

  • Actually purge expired content and assets when the 120-day window elapses.

  • Allow archiving, restoring, and permanent deletion of a single item or a bulk selection (bulk selection shipped in PR #728 / sub-issue #727 — see the Bulk Actions guide).

  • Filter and sort the Archive before acting: search, status filter, skills filter, grid/list view, and a Sort by control (Days Left / Alphabetical).

Non-Goals:

  • Automatic scheduler-based purge execution in this feature scope. Resolved (v2.0): the scheduler-based purge shipped in PR #770 (purge-expired-archived cron + cron-purge-expired.yml); see “Retention, Warning & Auto-Purge”.

  • Cryptographic wipe guarantees for storage objects. Still out of scope: purge removes the storage objects and the metadata row; no secure-erase guarantees are made.

  • Full policy engine for retention customization per tenant. Still out of scope: the retention window is a fixed constant (ARCHIVE_RETENTION_DAYS = 120).

Glossary:

  • Soft Delete / Archive: Marking content or an asset as archived via status/metadata fields, without removing the DB row or the storage object.

  • Archive: The UI and API surface for archived items. Renamed from “Trash Bin” in PR #711; the page lives at /creator/archive.

  • Purge: Permanent deletion of the metadata row and its storage object(s). Irreversible.

  • Retention Window: 120-day period after archiving, measured from archived_at (quests/adventures) or deleted_at (assets). Mirrored to expires_at for assets.

  • Warning Window: The final 30 days of the retention window. Items crossing day 90 are picked up by the daily warning cron and the creator receives one email listing everything expiring.


3. High-Level Architecture

System Diagram:

Frontend: Next.js (App Router), React, Tailwind CSS, Shadcn/UI components (Button, Card, Badge, Dialog, DropdownMenu), Sonner toast notifications, next/image.

Backend: Next.js route handlers, TypeScript, Zod validation (shared/schemas/contentManagementSchema.ts), Supabase Auth, agency ownership helpers, ApiResponseHelper response envelope, EmailService + React Email templates.

Database: Supabase Postgres with asset_metadata, quests, and adventures (publishing_status = 'archived' + archived_at / deleted_at + deletion_warning_sent_at).

Storage: Supabase Storage bucket public-assets (media files and video thumbnail sidecars).

Scheduled jobs: GitHub Actions workflows cron-pending-deletion.yml (warning) and cron-purge-expired.yml (purge), both firing daily at 10:00 UTC against the develop (:3000) and staging (:3001) deployments.

Authentication note: The platform migrated from Clerk to Supabase Auth in September 2026. asset_metadata.creator_id, quests.creator_id, and adventures.creator_id hold the internal Supabase user UUID (app_users.id). Legacy clerk_id / user_clerk_id column names and the COMMENT ON COLUMN text in older migrations (“Clerk user ID”) are naming artifacts only — archive code must never treat them as Clerk IDs.


4. Detailed Design & Implementation

Data Model / Schema

The feature is built on the asset_metadata table (background assets) plus archive columns on quests and adventures.

asset_metadata — final effective structure (after the April, July, and August 2026 migrations):

asset_metadata (
id uuid primary key default gen_random_uuid(),
creator_id text not null check (creator_id != ''),
-- creator_id = app_users.id (internal Supabase Auth user UUID)
 
file_name text not null,
file_path text, -- Storage path (NULL for external URLs)
file_url text, -- public URL (Supabase or external)
external_url text, -- original URL when source = 'external'
file_type text, -- MIME type
file_size integer, -- bytes (NULL for external)
 
asset_type text not null,
-- asset_type: IMAGE | AUDIO | VIDEO | DOCUMENT | BADGE
-- | quest_profile | quest_mentor | adventure-profile
-- | adventure-cover | quest_* (see 20260813 migration)
usage_context text,
source text not null default 'uploaded'
check (source in ('uploaded','external')),
thumbnail_url text,
 
deleted_at timestamptz default null, -- archive timestamp (NULL = active)
expires_at timestamptz default null, -- target purge date (+120 days)
deletion_warning_sent_at timestamptz default null, -- day-90 marker (NULL = not warned)
 
created_at timestamptz not null default now(),
updated_at timestamptz not null default now()
);

quests / adventures (archive-relevant columns):

  • publishing_status = 'archived' — the archived state used by every list/filter/restore query.

  • archived_at timestamptz — set when the item is archived (PR #711 migration).

  • deletion_warning_sent_at timestamptz — set after the day-90 warning email is sent.

Archive-related migrations (apply in order where not already deployed):

Migration

Purpose

20260424052731_soft_delete_optional_purge_columns.sql

Adds deleted_at + expires_at and the deleted_at index to asset_metadata (pre-feature groundwork, issue #437)

20260424053322_create_asset_metadata_table.sql

Creates asset_metadata, its indexes, the updated_at trigger, and the four owner RLS policies

20260728_add_archived_at_to_quests_adventures.sql

Adds archived_at + indexes to quests and adventures for the 120-day countdown

20260729_backfill_archived_at_and_warning_tracking.sql

Backfills archived_at = updated_at for rows already archived, adds deletion_warning_sent_at to all three tables, adds the partial warning indexes

20260813_add_document_asset_type.sql

Extends the asset_type CHECK constraint (IMAGE / AUDIO / VIDEO / DOCUMENT / BADGE / profile & cover contexts / quest_%) — Asset Library work that also widened the archiveable set

Indexes relevant to archive queries:

  • idx_asset_metadata_deleted_at, idx_asset_metadata_creator_id, idx_asset_metadata_created_at

  • idx_quests_archived_at, idx_adventures_archived_at

  • Partial warning indexes: idx_quests_deletion_warning, idx_adventures_deletion_warning, idx_asset_metadata_deletion_warning — all filtered on ... IS NOT NULL AND deletion_warning_sent_at IS NULL.

Row Level Security: asset_metadata has RLS enabled with four owner policies (select / insert / update / delete _own), each gated on creator_id = (auth.jwt() ->> 'sub'). Important: the server routes use the service-role client (lib/supabase.ts), which bypasses RLS. Route-handler authorization (the helpers below) is the enforcement point; RLS is defense-in-depth for direct PostgREST access. expires_at is written when an asset is archived but is not read by the cron jobs — both the warning and purge queries key off deleted_at (assets) and archived_at (content), so a manual expires_at edit cannot change purge timing.

Archive Lifecycle

Background assets:

  1. Creator chooses Archive on an asset card in Background Assets (or bulk-selects and uses the action bar).

  2. DELETE /api/creator/delete-assets validates asset_id / asset_ids (Zod) and verifies ownership per asset.

  3. The API sets deleted_at = now and expires_at = now + 120 days.

  4. GET /api/creator/list-assets excludes archived rows (deleted_at IS NULL); GET /api/creator/get-trash-assets returns only archived rows, newest-first, and maps DB columns to the frontend shape (name, url, deleted_at, …).

  5. /creator/archive shows each card with a countdown badge derived from deleted_at via getDaysRemaining.

  6. Restore (PATCH /api/creator/restore-assets) clears deleted_at and expires_at and the asset reappears in the library.

  7. Purge (DELETE /api/creator/purge-assets) deletes the row first, then removes the storage object (+ the .jpg video-thumbnail sidecar for videos).

Quests & adventures:

  1. Creator chooses Archive on a card in the Quests/Adventures tab (or bulk-selects and uses the action bar).

  2. PATCH /api/creator/archive-content validates the payload and verifies ownership per item.

  3. The API sets publishing_status = 'archived', archived_at = now, and updated_at = now.

  4. GET /api/creator/list-archived returns archived quests and adventures (with computed adventure total fees) for the Archive tab; active list routes exclude publishing_status = 'archived'.

  5. The Archive tab renders a countdown badge from archived_at; archived quests open read-only in the quest editor until restored.

  6. Restore (PATCH /api/creator/restore-content) sets publishing_status = 'draft', clears archived_at, and returns the item to the top level (clears quest_folder_id / adventure_folder_id / project_folder_id).

  7. Permanent delete (DELETE /api/creator/permanent-delete) requires confirm_text = 'DELETE', deletes the row, then cleans up {content_type}/{id} storage files and the matching asset_metadata rows.

Retention, Warning & Auto-Purge

Stage

Threshold

Endpoint

Workflow

Day 0

archive action

content: PATCH /api/creator/archive-content; assets: DELETE /api/creator/delete-assets

—

Day 90 (30 days left)

deleted_at / archived_at ≤ now − (120 − 30) days and deletion_warning_sent_at IS NULL

GET /api/cron/check-pending-deletion

cron-pending-deletion.yml (“Archive Deletion Warning”)

Day 120

deleted_at / archived_at ≤ now − 120 days

GET /api/cron/purge-expired-archived

cron-purge-expired.yml (“Archive Deletion Purge”)

Warning cron (check-pending-deletion):

  • WARNING_THRESHOLD_DAYS = ARCHIVE_RETENTION_DAYS − 30 (= 90), derived from lib/archive/getDaysRemaining.ts so the threshold can never drift from the retention constant.

  • Queries expired-soon quests, adventures, and assets in one pass, groups them by creator, and sends one email per creator listing every item as • {title} ({type}).

  • Email: AutoDeletionWarningEmail rendered through renderAutoDeletionWarningEmail; subject Action Required: {n} archived item(s) will be deleted in 30 days; the CTA links to /creator; agency branding is applied when the creator belongs to an agency.

  • After a successful send, the affected IDs are marked with deletion_warning_sent_at = <timestamp>. This is the recovery mechanism: the query is not a sliding time window, so a failed or missed run is caught on the next run instead of silently skipping items.

  • Assets with no app_users email are counted in skipped and left unmarked.

  • The response is a JSON counter summary: { type, sent, skipped, errors, message }.

Purge cron (purge-expired-archived):

  • Computes one cutoff (now − 120 days) and runs purgeExpiredQuests, purgeExpiredAdventures, and purgeExpiredAssets from lib/archive/purgeArchivedContent.ts in parallel.

  • Each function: selects expired rows → deletes the DB rows → cleans up storage only for rows that were actually deleted (guarding against FK failures leaving orphaned references).

  • Storage cleanup runs through Promise.allSettled, so one failed cleanup cannot reject the whole batch. Quests/adventures clean up {table}/{id} recursively (including asset_metadata rows matched on file_path), assets remove file_path plus the video thumbnail sidecar.

  • Storage cleanup is best-effort with no rollback (accepted trade-off, matching permanent-delete): a storage failure after a successful DB delete leaves an orphaned object. See Known Limitations.

  • The response reports per-entity { deleted, errors } plus a summary message.

Cron authentication: both endpoints require CRON_SECRET and accept it either as Authorization: Bearer <secret> or ?secret=. The workflows use the Authorization header (PR #725): the generated secret contains +, which a query string decodes to a space and silently fails the comparison. Missing CRON_SECRET returns 500; a mismatch returns 401.

Workflow hardening (PR #794): each workflow runs two steps (develop + staging) over SSH with appleboy/ssh-action, extracts the secret from /var/www/wyzquests/config/{develop,staging}.env with sed (tolerating whitespace, quotes, and CRLF), and curls with --retry 2 --retry-delay 30 --max-time 90. Worst case is 3 attempts ≈ 5.5 minutes, inside command_timeout: 6m and timeout-minutes: 15. --retry-all-errors is deliberately absent so auth/404 failures fail fast instead of burning the retry budget. A non-200 response fails the job. Both workflows also expose workflow_dispatch for manual runs.

API Specification

Archive / restore / purge — quests & adventures:

Endpoint

Method

Body

Behaviour

/api/creator/archive-content

PATCH

{ content_id?, content_ids?, content_type: "quests" | "adventures" }

Sets publishing_status = 'archived' + archived_at; returns { archivedIds, missingIds, skippedIds }

/api/creator/restore-content

PATCH

same shape

Sets publishing_status = 'draft', clears archived_at and folder associations; returns { restoredIds, missingIds, skippedIds }

/api/creator/permanent-delete

DELETE

{ content_id?, content_ids?, content_type, confirm_text: "DELETE" }

Deletes the rows, then storage + asset metadata; invalid confirm_text writes an audit_logs entry and returns 400

/api/creator/list-archived

GET

—

{ archivedQuests, archivedAdventures }; adventures include total_quest_fee

Archive / restore / purge — background assets:

Endpoint

Method

Body

Behaviour

/api/creator/delete-assets

DELETE

{ asset_id?, asset_ids? }

Sets deleted_at + expires_at (+120 days); returns { archivedIds }

/api/creator/restore-assets

PATCH

same shape

Clears deleted_at / expires_at; returns { restoredIds, missingIds, skippedIds }

/api/creator/purge-assets

DELETE

{ asset_id?, asset_ids?, confirm_text: "DELETE" }

Deletes rows, then storage (+ video sidecar); returns { deletedIds, missingIds }

/api/creator/list-assets

GET

—

Active assets: deleted_at IS NULL, newest first

/api/creator/get-trash-assets

GET

—

Archived assets: deleted_at IS NOT NULL, newest first; maps file_name → name, file_url/external_url → url

Cron endpoints (secret-protected):

Endpoint

Method

Auth

Behaviour

/api/cron/check-pending-deletion

GET

Authorization: Bearer $CRON_SECRET (or ?secret=)

Sends day-90 warning emails, marks deletion_warning_sent_at

/api/cron/purge-expired-archived

GET

same

Permanently purges content and assets past day 120

Notes:

  • Every archive/restore/purge route accepts either a single ID (content_id / asset_id, backward compatible) or an array (content_ids / asset_ids), validated by archiveContentSchema, restoreContentSchema, permanentDeleteSchema, bulkAssetIdsSchema, and purgeAssetsSchema in shared/schemas/contentManagementSchema.ts.

  • Ownership is verified per item, not per request: quests/adventures additionally accept the MFPS folder-admin fallback (canManageItemsInFolders), assets are creator/agency only.

  • All non-cron routes return the standard envelope ({ success, message, data, error }) via ApiResponseHelper; the cron routes return a JSON summary directly.

  • Status codes: 400 (invalid payload / already archived / not archived / wrong confirm token), 401 (missing session), 403 (not the owner and not a folder manager), 404 (not found), 500 (DB/storage failure).

UI Integration

  • Quests / Adventures / Archive tabs (components/creator/MyContent.tsx): the tab is labelled Archive and is an internal state key (shownContent === "archive") that fetches /api/creator/list-archived. The archive tab shares the quests/adventures toolbar — search, grid/list toggle, status filter, skills filter — and adds the ArchiveSortDropdown (Days Left / Alphabetical) to the left of the “View Library” button. An error banner with a Retry button is rendered when the archive fetch fails.

  • components/creator/TrashContent.tsx: renders the filtered/sorted archived quests and adventures as a controlled component (items, totalCount, isLoading, error, viewMode, onRetry, onItemsRemoved). Provides grid + list views, {days}d left badges (turning destructive at ≤ 3 days), Restore / Delete Forever per card, an “Archive is empty” state, a “No content matches the selected filters” state, and the bulk selection UI.

  • /creator/archive (app/creator/archive/page.tsx): the background-assets archive. Header reads “Archive” with “Items here will be permanently deleted after 120 days.”, an ArchiveSortDropdown, and a 4-column card grid with thumbnails (next/image), countdown badges, and Restore / Delete Permanently actions.

  • Background Assets (app/creator/background-assets/page.tsx): header row carries the SortDropdown (Alphabetical / Date Added) and an Archive button (archive icon) that links to /creator/archive. AssetList shows Edit | Archive | Delete Permanently per card, keeps parent state in sync on rename (onAssetsChange), re-clears selection when the sorted list changes, and hides per-item actions while selection mode is active.

  • DeleteAssetModal: title “Move to Archive”, body “…You can restore it anytime within the next 120 days.”, CTA “Move to Archive”.

  • Permanent deletion always goes through ConfirmDestructiveModal with the typed token DELETE (shared standard from issue #777).

  • Quest editor: archived quests render a read-only banner (“This quest is archived — Archived quests are read-only. Restore this quest from the Archive tab on your dashboard to make changes.”) and block edits.

Bulk Actions (sub-issue #727)

Bulk select / archive / restore / delete for all three surfaces shipped in PR #728 and is documented in the Bulk Actions Internal Technical Guide (selection model, SelectionActionBar, confirmation contract, folder-aware authorization). This guide only records the archive-side contract it relies on: the array payload shapes above, the per-item affected-ID responses, and the archive surfaces that expose the selection UI.


5. Infrastructure & Operations

Dependencies:

  • asset_metadata table, archive columns on quests / adventures, and the partial warning indexes (migrations above).

  • Supabase Storage bucket public-assets.

  • Supabase Auth session + app_users resolution for ownership.

  • Ownership checks via agency auth helpers (getCreatorAuthContext, verifyAgencyResourceOwnership, agencyResourceFilter) and the MFPS folder fallback for content.

  • Email delivery (EmailService, SMTP/email provider) for the day-90 warning; failures are counted as errors and retried on the next cron run (the item stays unmarked).

  • GitHub Actions secrets: HOSTINGER_IP, USERNAME, SSH_PRIVATE_KEY, CRON_SECRET.

  • CRON_SECRET present in /var/www/wyzquests/config/develop.env and config/staging.env on the VPS.

  • Frontend fetch flows use force-dynamic + revalidate = 0 on the list routes for freshness after archive/restore.

Monitoring & Alerting:

Current behaviour is log-driven, toast-driven, and workflow-driven:

  • API handlers log server errors with console.error; ApiResponseHelper.error logs 5xx responses and stack traces.

  • UI surfaces Sonner toasts on fetch/archive/restore/purge success and failure.

  • The two GitHub Actions workflows are the de-facto alerting channel: a non-200 curl result prints FAIL (HTTP <code>) and fails the job, which notifies the repository watchers. Both expose manual workflow_dispatch runs.

  • Cron responses carry sent / skipped / errors counters (and per-entity deleted / errors for the purge) in the workflow logs.

  • No dedicated metrics/alerts currently exist for archive failure rate, warning-email delivery rate, or purge drift. (Still open — see Handover Tasks.)

Deployment Plan:

  1. Validate migration state in the target environment (apply the archive migrations in order where not already present; the maintainer applies migrations).

  2. Ensure CRON_SECRET is set in both env files on the VPS and as a GitHub repository secret, then reload: pm2 reload wyzquests-dev --update-env and pm2 reload wyzquests-staging --update-env.

  3. Confirm RLS and ownership helpers in agency and creator contexts.

  4. Run archive / restore / purge smoke tests with uploaded and external assets, and with quests/adventures (including one inside a folder, to verify restore returns it to root).

  5. Verify active-list / archive-list filtering consistency on both surfaces.

  6. Confirm video thumbnail cleanup during purge (the .jpg sidecar).

  7. Trigger both workflows manually once (“Run workflow”) and confirm HTTP 200 on develop and staging.

  8. Confirm the day-90 warning email renders with agency branding and that deletion_warning_sent_at is stamped afterwards.


6. Testing & Quality Assurance

Test Strategy:

  • API / contract tests: valid and invalid UUID payloads, single-ID vs array payloads, ownership-mismatch rejection, confirm_text enforcement, and the exact affected-ID response sets. Existing jest coverage today: tests/creator/api/background-assets/deleteAsset.test.ts (archive request contract), tests/api/background-assets-thumbnail.test.ts, and tests/unit/image-src.test.ts / tests/unit/image-svg-passthrough.test.tsx for the archive-card image policy.

  • UI tests: archive action removes the card from the active list; archive lists render items with countdown badges; restore makes the item reappear in the active library; action buttons hide during selection mode.

  • Integration / manual: purge removes both the storage object and the metadata row; the warning cron groups per creator and sends one email; re-running a cron marks only items that were successfully notified.

  • Cron workflow verification: --retry 2 --retry-delay 30 --max-time 90 with command_timeout: 6m, and a non-200 failing the job.

Known Limitations:

  • expires_at is set but no automatic background purge scheduler is shown in current implementation. Resolved (v2.0): the purge scheduler shipped in PR #770 (/api/cron/purge-expired-archived + cron-purge-expired.yml); expires_at remains written for display/reporting but the crons key off deleted_at / archived_at.

  • Permanent delete confirmation keyword enforcement is currently UI-side only in the purge modal. Resolved (v2.0): the server now double-checks the token — purgeAssetsSchema requires confirm_text = 'DELETE', and permanent-delete validates confirm_text === 'DELETE' (writing an audit_logs row on failure).

  • Still open — no automated test suite covers the archive → restore → purge lifecycle. Coverage today is limited to the client-side archive request contract and the asset-thumbnail/image-policy suites; the cron endpoints and lib/archive/purgeArchivedContent.ts have no direct tests.

  • Error telemetry is not centralized (console + toasts + workflow logs only).

  • Best-effort storage cleanup: purge deletes DB rows first, so a storage failure can orphan objects; there is no orphan-file sweeper.

  • Purge granularity: the purge cron deletes whole content items and asset rows; there is no soft-delete bin for purged data (by design, irreversible).

  • AssetList.tsx, MyContent.tsx, and TrashContent.tsx still carry legacy “trash” naming internally (fetchTrashedAssets, TrashBinPage, /api/creator/get-trash-assets, TrashContent), and the delete-assets route name is kept for backward compatibility even though the UI says “Archive”. Renames were deliberately not churned to avoid breaking callers.


7. Maintenance & Support

Troubleshooting:

  • Asset still visible after archive: check the deleted_at update succeeded and that the active list is not serving a cached response (list-assets sets force-dynamic + revalidate = 0).

  • Content still visible after archive: verify publishing_status = 'archived' and archived_at were written (route uses PATCH /api/creator/archive-content).

  • Asset not in Archive: verify the get-trash-assets filter (deleted_at IS NOT NULL) and the agency scope filter; check ownership.

  • Content not in Archive tab: verify list-archived (publishing_status = 'archived') and the agency scope filter.

  • Restore fails: confirm the row exists and is owned by the requester (or the requester is a folder admin for quests/adventures); restore of content also clears folder associations by design.

  • Purge removes the DB row but the file remains: inspect the storage remove call and file_path correctness; remember cleanup is best-effort and non-transactional, so a failed storage call leaves an orphan.

  • Purge cron reports 0 for a long time: verify rows actually passed archived_at / deleted_at ≤ cutoff, that the migration was applied, and that publishing_status is exactly 'archived'.

  • Warning emails not sent: check CRON_SECRET on the VPS and in the GitHub secret, then check the endpoint returns 200; a missing secret returns 500 and a mismatch returns 401. Verify deletion_warning_sent_at is NULL for the intended rows (a previously warned row is intentionally skipped).

  • Warning email sent but not received: check app_users.email for the creator (missing email counts as skipped), and the email provider/EmailService logs.

  • Cron workflow fails only on staging: expected until the normal develop → staging sync deploys the branch; the staging step targets :3001.

  • 401 from a cron step after rotating the secret: confirm the secret has no trailing CRLF/quotes (the sed extraction strips them) and that the header form is used.

Week 12 Handover Tasks for Christian (To Do):

  • Confirm Week 12 acceptance criteria for archive-retention behaviour. — Resolved (v2.0): acceptance criteria verified against the shipped implementation (issue #37 and sub-issue #727 closed).

  • Add automated tests for archive → restore → purge lifecycle. — Still open. No automated suite covers the cron endpoints or purgeArchivedContent.ts; add jest coverage for the purge functions and an API-level test for the two cron routes.

  • Decide whether to add server-side enforcement for typed permanent delete challenge. — Resolved (v2.0): server-side confirm_text = 'DELETE' enforcement shipped (issue #777; purgeAssetsSchema + permanent-delete).

  • Propose/implement retention-job strategy for expires_at auto purge. — Resolved (v2.0): PR #770 shipped the daily purge cron keyed off deleted_at / archived_at.

  • Add operational metric hooks (archive success rate, restore success rate, purge failures). — Still open. Today’s signals are workflow pass/fail plus console logs; a metric/alerting hook is still a follow-up.

Changelog:

  • 1.0 - Handover Draft: Technical documentation prepared for implementation/hardening handoff, July 2026.

  • 2.0 - Archive overhaul documented (Updated by Christian Denzon, 09/30/2026): Trash → Archive rename and /creator/trash → /creator/archive; retention raised 30 → 120 days via ARCHIVE_RETENTION_DAYS; archived_at + deletion_warning_sent_at schema and backfill migrations; day-90 grouped warning email (AutoDeletionWarningEmail) with idempotent marking; day-120 auto-purge cron (purgeArchivedContent.ts, cron-purge-expired.yml) with parallel best-effort storage cleanup; cron authentication switched to Authorization: Bearer (PR #725) and both workflows hardened with retries/timeouts (PR #794); archive sort (Days Left / Alphabetical) and the shared archive toolbar (PR #770); Supabase Auth wording; References corrected to the real issue/PR links; resolved Non-Goals and Known Limitations marked inline. PRs: #711, #725, #770, #794.


Was this article helpful?