Skip to main content

Secret Santa

@aaronge/secret-santav2026.11.02.1· MIT· 19d agoBEHAVIORSWORKFLOWSEXTENDS
01README

Family Secret Santa: a fair constrained draw (couples excluded, no repeats from last year), a personal encrypted reveal link per person to a cheeky ASCII-Santa page, and either bulk SMS through Twilio or a private links file you send yourself (free, no Twilio needed).

02Behaviors1
@aaronge/secret-santav2026.11.02.1secret_santa.ts

Global Arguments

ArgumentTypeDescription
eventName?stringEvent name used in the SMS body.
yearnumberThe year being drawn. Draws are stored per year, so last year's results can be avoided next time.
baseUrlstringPublic URL of the static reveal page, e.g. https://you.github.io/secret-santa/. The encrypted token is appended after #.
participantsarrayEveryone taking part. At least three people are needed for a draw where nobody gets themselves and exclusions can still be satisfied.
exclusions?arrayPairs of names who must not draw each other, e.g. couples. Applies in both directions.
avoidRepeatYears?numberNobody gets the same person they bought for in this many previous years. 0 turns repeat avoidance off.
history?arrayEarlier draws entered by hand (e.g. last year's, done on paper). Draws made by this model are remembered automatically.
messageTemplate?stringSMS body. Placeholders: {name}, {event}, {year}, {link}. Must contain {link}.
shortener?enumShorten each reveal link before it goes in the SMS. is.gd is free and keeps the #fragment, but is.gd then holds the full links (and so could read the pairings). none sends the full link.
fn draw(redraw?: boolean)
Draw this year's Secret Santa. Keeps an existing draw for the year unless redraw is true, so re-running the workflow never reshuffles after links have gone out.
ArgumentTypeDescription
redraw?booleanThrow away this year's existing draw and draw again. Anyone already sent a link will have a stale one.
fn compose()
Turn this year's draw into one SMS per participant, each with a personal encrypted reveal link. Writes the sensitive outbox resource.
fn verify()
Decrypt every composed link and re-check the draw rules. Writes linkCheck with ok=true/false; a workflow assert should gate sending on it.
fn export_links(path?: string, only?: array)
Write each person's message and reveal link to a private file (readable only by you) so you can send them yourself by email, WhatsApp or by hand. Free, with no Twilio account needed. Re-checks the links first.
ArgumentTypeDescription
path?stringWhere to write the file. Defaults to ~/secret-santa-links-<year>.txt. Keep it out of git.
only?arrayExport only these names (case-insensitive). Empty means everyone.

Resources

draw(infinite)— Who buys for whom, one instance per year (draw-<year>). Kept so later years can avoid repeats.
drawSummary(infinite)— Non-secret facts about the latest draw: headcount, constraints applied, solver attempts.
outbox(infinite)— The SMS for each participant, with phone numbers and reveal links. Stored in the vault (sensitive), never in plain data.
linkCheck(infinite)— Pass/fail result of decrypting every composed link and re-validating the draw. Never names pairings.
linkExport(infinite)— Where export_links wrote the private links file, and how many people it covers. Never holds the links.
03Workflows2
@aaronge/secret-santa06ed8663-689b-4ddd-8f13-9bd060ec005f

Draw this year's Secret Santa (kept if already drawn), compose one SMS per person with an encrypted reveal link, verify every link, then text them via Twilio. Dry run by default; set testRecipient to text only yourself first. People without a phone number are skipped; hand them their link with the @aaronge/secret-santa-links workflow. Needs a Twilio account. Run manually — there is no schedule.

prepareDraw (or keep the existing draw), compose the messages, and re-check every link.
1.draw${{ inputs.santaModel }}.draw
2.compose${{ inputs.santaModel }}.compose
3.verify${{ inputs.santaModel }}.verify
checkRefuse to send unless every link decrypts and the draw obeys every rule.
1.links-ok
sendText everyone (or just testRecipient). Dry run unless dryRun is false.
1.send-outboxtwilio.send_outbox
@aaronge/secret-santa-links88bd995a-7b94-46a9-8072-67c851b799cf

The free alternative to texting: draw this year's Secret Santa (kept if already drawn), compose each person's message and encrypted reveal link, verify every link, then write them all to a private file for you to send by email, WhatsApp or by hand. No Twilio account needed. Run manually; there's no schedule.

prepareDraw (or keep the existing draw), compose the messages, and re-check every link.
1.draw${{ inputs.santaModel }}.draw
2.compose${{ inputs.santaModel }}.compose
3.verify${{ inputs.santaModel }}.verify
checkRefuse to export unless every link decrypts and the draw obeys every rule.
1.links-ok
exportWrite every message to a private file (readable only by you) for sending yourself.
1.export-links${{ inputs.santaModel }}.export_links
04Extends1
@keeb/twilio/messagingtwilio_outbox.ts
fn send_outbox(sourceModel: string, outbox?: string, dryRun?: boolean, only?: array, throttleMs?: number, messages?: union)
Send every message in another model's outbox resource, one Twilio request each, throttled. Dry run by default.
ArgumentTypeDescription
sourceModelstringName of the model holding the outbox, e.g. santa-family.
outbox?stringInstance name of the outbox resource on that model.
dryRun?booleanWhen true (the default), log what would be sent and send nothing.
only?arraySend only to these recipient names (case-insensitive), e.g. yourself for a test. Empty means everyone.
throttleMs?numberPause between sends, to stay under Twilio's rate limit.
messages?unionThe outbox\

Resources

bulkSend(infinite)— Summary of one send_outbox run: who was texted, who failed and why, who was skipped.
05Stats
A
100 / 100
Downloads
4
Archive size
34.1 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
06Platforms
07Labels