@tannerlinsley/skylight

Skylight

Import skylight from kody:@tannerlinsley/skylight. Read operations accept {operation,args}; inventory returns account/frame/profile/color/mapping information without event titles. Call {operation:'tools',mode:'write'} for writers or {operation:'tools',name:'skylight_create_chore'} for the exact JSON schema. All 114 upstream operations are present, including 77 writes.

Write protocol

1. Read current objects and resolve exact IDs. Frame-scoped writes require explicit frameId. Do not guess IDs or apply an implicit first-frame default.
2. Call {operation,args} to validate and get a no-network preview. Unknown arguments are errors, not silently discarded.
3. For every deletion, show the exact objects and wait for explicit user approval. Before bulk edits, present the proposed change set. Source-calendar, user-access and public-display changes need a specific request. Setup authorization is not authorization to change production objects.
4. Once the requested change is authorized, call with the same operation and args, top-level confirm:true, and previewToken from the preview. Do not use args.confirm as a substitute. dryRun:true overrides confirmation. A changed operation or argument requires a new preview.
5. Verify the result with a read. Preview tokens do not provide idempotency, so inspect state after an uncertain write instead of retrying blindly.

Use file:{name,base64}, maximum 20 MiB, for the three file tools. Do not provide image_path or read arbitrary local files. Read the source tool descriptions for best-effort endpoints. Apple app_specific_password must be a Kody secret placeholder approved for app.ourskylight.com; collect it through the private secret setup page, never chat. Keep secrets, raw tokens and cookie values out of logs and returns.

skylight_clear_list also requires item_ids from a fresh skylight_get_list_items read. The handler aborts if the set changed. For bulk operations spanning multiple calls, show the entire plan and then execute each confirmed operation, stopping on a failure.

Maintenance

Run npm test. Tests inject a fake client and fake S3 uploader; never replace these with production credentials. All 77 writers must preview without network and dispatch against the mock. After publish, statically import the package in execute and verify tools, one no-network write preview and skylight_healthcheck. Do not use a real write to smoke-test setup. Package is private and must remain so.

The account is an approved viewer and users-list returns 403. Enabling operations does not grant provider permissions. Surface an actual 403 rather than silently switching to Google Calendar or another account. All writes in this release are locally tested, not production-tested.