From 3a221e14589be7bfe03886dc596ae5824457542c Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Fri, 2 Oct 2026 15:21:57 +0000 Subject: [PATCH] todoist 0.1.0: a read-only drive app hosting the Todoist lens (#99, #46) Refs #99, #46. Give integrations/issue-tracker/todoist.ts a host: a drive app in integrations/issue-tracker/todoist-app/ (apps.mjs APP_FOLDERS maps the catalog id `todoist` there) that connects through store.proxy.connect, reads the active tasks and projects through the host's proxy client, and imports them into rows of the shared class issue-v1, adopting the class on first open like the GitHub issues app (renders, row-extras, classtype). Shared fields go through ontology-kit's resolver; the Todoist task id, presence, last-seen, priority, project and source are row extras. The pass runs #99's disappearance behaviour as todoist.ts defines it: a task missing from a complete read is looked up by id once and marked completed, deleted, unavailable or unconfirmed; only completed closes it, a partial read settles nothing, no row is removed, nothing is sent to Todoist. A refresh that finds nothing changed writes no row: last-seen is kept off active rows (the App records the read's time once). The mock-proxy fixture in fixtures/todoist/ now serves SYNTHETIC rows (synthetic.mjs, hand-written from Todoist's API v1 documentation, invented data) until #46 records api/, with drivers (completeTask, reopenTask, deleteTask, removeTask, failNext, snapshot); it is registered with the mock proxy. The issue-tracker lane gains e2e/todoist.spec.ts: catalog install, connect, five issue-v1 rows, a reload that leaves every row byte-for-byte, a task completed in Todoist that turns up done, one made unreachable that stays open as unavailable. Catalog: `devonian-todoist` becomes the app entry `todoist` (0.1.0, apps/todoist/0.1.0/ui.js, 25,926 bytes; enabled: false). Co-Authored-By: Claude Fable 5.1 --- apps/todoist/0.1.0/ui.js | 1 + docs/design/bundles.md | 4 +- integrations/READINESS.md | 30 +- integrations/catalog.json | 23 +- integrations/issue-tracker/README.md | 82 +++- .../issue-tracker/e2e/todoist.spec.ts | 281 ++++++++++++ .../issue-tracker/fixtures/todoist/record.mjs | 20 +- .../fixtures/todoist/scenario.mjs | 226 ++++++++-- .../fixtures/todoist/synthetic.mjs | 136 ++++++ .../todoist-app/atomic-lib-shim.ts | 23 + .../issue-tracker/todoist-app/build.mjs | 78 ++++ .../issue-tracker/todoist-app/build.test.ts | 63 +++ .../issue-tracker/todoist-app/controller.ts | 196 ++++++++ .../issue-tracker/todoist-app/drive.ts | 329 ++++++++++++++ .../issue-tracker/todoist-app/fakeStore.ts | 202 +++++++++ .../issue-tracker/todoist-app/main.ts | 99 +++++ .../issue-tracker/todoist-app/package.json | 7 + .../issue-tracker/todoist-app/read.ts | 193 ++++++++ .../issue-tracker/todoist-app/store.ts | 136 ++++++ .../issue-tracker/todoist-app/sync.test.ts | 417 ++++++++++++++++++ .../issue-tracker/todoist-app/sync.ts | 346 +++++++++++++++ .../issue-tracker/todoist-app/tsconfig.json | 14 + .../issue-tracker/todoist-fixture.test.ts | 187 +++++--- integrations/issue-tracker/vitest.config.ts | 1 + integrations/lanes.json | 7 +- integrations/localthought/README.md | 8 +- integrations/localthought/fixtures/index.mjs | 7 +- integrations/localthought/mock-proxy.test.mjs | 6 +- integrations/tooling/apps.mjs | 4 +- integrations/tooling/apps.test.mjs | 1 + 30 files changed, 2986 insertions(+), 141 deletions(-) create mode 100644 apps/todoist/0.1.0/ui.js create mode 100644 integrations/issue-tracker/e2e/todoist.spec.ts create mode 100644 integrations/issue-tracker/fixtures/todoist/synthetic.mjs create mode 100644 integrations/issue-tracker/todoist-app/atomic-lib-shim.ts create mode 100644 integrations/issue-tracker/todoist-app/build.mjs create mode 100644 integrations/issue-tracker/todoist-app/build.test.ts create mode 100644 integrations/issue-tracker/todoist-app/controller.ts create mode 100644 integrations/issue-tracker/todoist-app/drive.ts create mode 100644 integrations/issue-tracker/todoist-app/fakeStore.ts create mode 100644 integrations/issue-tracker/todoist-app/main.ts create mode 100644 integrations/issue-tracker/todoist-app/package.json create mode 100644 integrations/issue-tracker/todoist-app/read.ts create mode 100644 integrations/issue-tracker/todoist-app/store.ts create mode 100644 integrations/issue-tracker/todoist-app/sync.test.ts create mode 100644 integrations/issue-tracker/todoist-app/sync.ts create mode 100644 integrations/issue-tracker/todoist-app/tsconfig.json diff --git a/apps/todoist/0.1.0/ui.js b/apps/todoist/0.1.0/ui.js new file mode 100644 index 000000000..6b65169a9 --- /dev/null +++ b/apps/todoist/0.1.0/ui.js @@ -0,0 +1 @@ +var Jt=Object.freeze({v1:"https://ontola.github.io/atomic-plugins/ontology/v1"}),Ut=Object.freeze({"atomic-calendar-day":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-day",datatype:"https://atomicdata.dev/datatypes/date"}),"atomic-calendar-end-day":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-end-day",datatype:"https://atomicdata.dev/datatypes/date"}),"atomic-calendar-all-day":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-all-day",datatype:"https://atomicdata.dev/datatypes/boolean"}),"atomic-calendar-start":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-start",datatype:"https://atomicdata.dev/datatypes/string"}),"atomic-calendar-end":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-end",datatype:"https://atomicdata.dev/datatypes/string"}),"atomic-calendar-location":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-location",datatype:"https://atomicdata.dev/datatypes/string"}),"atomic-calendar-notes":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-notes",datatype:"https://atomicdata.dev/datatypes/string"}),"atomic-calendar-recurrence":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-recurrence",datatype:"https://atomicdata.dev/datatypes/json"}),"work-start":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/work-start",datatype:"https://atomicdata.dev/datatypes/timestamp"}),"work-end":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/work-end",datatype:"https://atomicdata.dev/datatypes/timestamp"}),"work-project":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/work-project",datatype:"https://atomicdata.dev/datatypes/atomicURL",classtype:"https://ontola.github.io/atomic-plugins/ontology/classes/work-project-v1"}),"work-person":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/work-person",datatype:"https://atomicdata.dev/datatypes/atomicURL",classtype:"https://ontola.github.io/atomic-plugins/ontology/classes/work-person-v1"}),"work-billable":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/work-billable",datatype:"https://atomicdata.dev/datatypes/boolean"}),"bank-account":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/bank-account",datatype:"https://atomicdata.dev/datatypes/string"}),"bank-currency":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/bank-currency",datatype:"https://atomicdata.dev/datatypes/string"}),"bank-amount":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/bank-amount",datatype:"https://atomicdata.dev/datatypes/string"}),"bank-value-date":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/bank-value-date",datatype:"https://atomicdata.dev/datatypes/date"}),"bank-booking-date":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/bank-booking-date",datatype:"https://atomicdata.dev/datatypes/date"}),"bank-description":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/bank-description",datatype:"https://atomicdata.dev/datatypes/string"}),"bank-reference":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/bank-reference",datatype:"https://atomicdata.dev/datatypes/string"}),"money-category":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/money-category",datatype:"https://atomicdata.dev/datatypes/string"}),"money-note":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/properties/money-note",datatype:"https://atomicdata.dev/datatypes/string"})}),N=Object.freeze({"event-v1":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/classes/event-v1",requires:Object.freeze(["https://atomicdata.dev/properties/name","https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-day"]),recommends:Object.freeze(["https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-end-day","https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-all-day","https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-start","https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-end","https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-location","https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-notes","https://ontola.github.io/atomic-plugins/ontology/properties/atomic-calendar-recurrence"])}),"issue-v1":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/classes/issue-v1",requires:Object.freeze(["https://atomicdata.dev/properties/name"]),recommends:Object.freeze(["https://atomicdata.dev/task/v1/status","https://atomicdata.dev/task/v1/body","https://atomicdata.dev/task/v1/assignee","https://atomicdata.dev/task/v1/due-date"])}),"time-entry-v1":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/classes/time-entry-v1",requires:Object.freeze(["https://ontola.github.io/atomic-plugins/ontology/properties/work-start"]),recommends:Object.freeze(["https://atomicdata.dev/properties/name","https://ontola.github.io/atomic-plugins/ontology/properties/work-end","https://ontola.github.io/atomic-plugins/ontology/properties/work-project","https://ontola.github.io/atomic-plugins/ontology/properties/work-person","https://ontola.github.io/atomic-plugins/ontology/properties/work-billable"])}),"work-project-v1":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/classes/work-project-v1",requires:Object.freeze(["https://atomicdata.dev/properties/name"]),recommends:Object.freeze([])}),"work-person-v1":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/classes/work-person-v1",requires:Object.freeze(["https://atomicdata.dev/properties/name"]),recommends:Object.freeze([])}),"bank-transaction-v1":Object.freeze({subject:"https://ontola.github.io/atomic-plugins/ontology/classes/bank-transaction-v1",requires:Object.freeze(["https://ontola.github.io/atomic-plugins/ontology/properties/bank-account","https://ontola.github.io/atomic-plugins/ontology/properties/bank-currency","https://ontola.github.io/atomic-plugins/ontology/properties/bank-amount","https://ontola.github.io/atomic-plugins/ontology/properties/bank-value-date"]),recommends:Object.freeze(["https://atomicdata.dev/properties/name","https://ontola.github.io/atomic-plugins/ontology/properties/bank-booking-date","https://ontola.github.io/atomic-plugins/ontology/properties/bank-description","https://ontola.github.io/atomic-plugins/ontology/properties/bank-reference","https://ontola.github.io/atomic-plugins/ontology/properties/money-category","https://ontola.github.io/atomic-plugins/ontology/properties/money-note"])})});var w="https://atomicdata.dev",z=`${w}/properties/parent`,wt=`${w}/properties/isA`,P=`${w}/properties/name`,_=`${w}/properties/shortname`,Tt=`${w}/properties/description`,vt=`${w}/properties/datatype`,St=`${w}/properties/recommends`,K=`${w}/properties/properties`,Y=`${w}/properties/classtype`,Ot=`${w}/classes/Property`,jt=`${w}/ontology/server/property/default-ontology`,R=N["issue-v1"].subject,E=`${w}/task/v1`,V=`${E}/status`,C=`${E}/body`,L=`${E}/due-date`,Z=`${E}/todo`,G=`${E}/done`,B="Todoist tasks",j={string:`${w}/datatypes/string`},Rt=[{key:"taskId",shortname:"todoist-task-id",name:"Todoist task",datatype:j.string,description:"The id of the Todoist task this row was imported from. The row\u2019s identity across imports."},{key:"presence",shortname:"todoist-presence",name:"Todoist presence",datatype:j.string,description:"Where the task stands in Todoist: active, completed, deleted, unavailable (gone, reason unknown) or unconfirmed (last known values; see Todoist last seen)."},{key:"lastSeen",shortname:"todoist-last-seen",name:"Todoist last seen",datatype:j.string,description:"When Todoist last returned this task, as an ISO 8601 date and time. Set only on a task that is no longer in the active list; an active task was seen at the app\u2019s last sync."},{key:"priority",shortname:"todoist-priority",name:"Todoist priority",datatype:j.string,description:"Todoist priority: Normal, Medium, High or Urgent."},{key:"project",shortname:"todoist-project",name:"Todoist project",datatype:j.string,description:"The name of the Todoist project the task is in."},{key:"source",shortname:"todoist-source",name:"Todoist source",datatype:j.string,description:"JSON text written by the Todoist app: the task as Todoist last sent it, with the app\u2019s presence fields. Edit it and the next import can no longer tell what Todoist said."},{key:"lastSync",shortname:"todoist-last-sync",name:"Todoist last sync",datatype:j.string,description:"When the Todoist app last read the complete active-task list, as an ISO 8601 date and time. On the App resource."}],Pt=["taskId","presence","lastSeen","priority","project","source"],I=t=>Array.isArray(t)?t.filter(o=>typeof o=="string"):[];async function At(t,o){let s=I(o.get(K)),e=new Map;for(let c of s){let r=(await t.getResource(c)).get(_);typeof r=="string"&&e.set(r,c)}let n=[],a={};for(let c of Rt){let r=e.get(c.shortname);r||(r=(await t.newResource({parent:o.subject,isA:[Ot],propVals:{[_]:c.shortname,[P]:c.name,[Tt]:c.description,[vt]:c.datatype}})).subject,n.push(r)),a[c.key]=r}return n.length>0&&await o.set(K,[...s,...n]).save(),a}async function xt(t,o){let s=(await t.getResource(o)).get(jt);if(typeof s=="string")return t.getResource(s);throw new Error("This app has no ontology of its own to add fields to.")}async function H(t,o,s){for(let e of I(o.get(wt))){let n=await t.getResource(e).catch(()=>{});for(let a of I(n?.get(St)??[]))if((await t.getResource(a).catch(()=>{}))?.get(_)===s)return a}}function X(t,o,s){if(!o)return!1;let e=I(t.get(o)??[]),n=s.filter(a=>!e.includes(a));return n.length?(t.set(o,[...e,...n]),!0):!1}var x=class extends Error{constructor(){super("This is another Issue table. The Todoist app imports only into its own table."),this.name="OtherTable"}};async function Q(t){let o=await t.getApp(),s=await t.getData();if(!s?.table)throw new Error("This app has no table to import into.");let e=await xt(t,o),n=await At(t,e),a=await t.getResource(o),c=X(a,await H(t,a,"renders"),[R]),r=X(a,await H(t,a,"row-extras"),Pt.map(m=>n[m]));(c||r)&&await a.save();let p=await t.getResource(s.table);if(p.get(z)!==o)throw new x;let l=p.get(Y)!==R,i=p.get(P)!==B;return l&&p.set(Y,R),i&&p.set(P,B),(l||i)&&await p.save(),{app:o,table:s.table,rowClass:R,properties:n}}async function tt(t,o){let s=(await t.getResource(o.app)).get(o.properties.lastSync);return typeof s=="string"&&s?s:void 0}async function et(t,o,s){let e=await t.getResource(o.app);e.get(o.properties.lastSync)!==s&&await e.set(o.properties.lastSync,s).save()}var ot=t=>t!=null&&t!=="";function Et(t){if(!t||typeof t.subject!="string"||!Array.isArray(t.requires)||!Array.isArray(t.recommends))throw new TypeError("a shared class needs subject, requires and recommends (import it from terms.mjs)")}function st({classes:t,lenses:o=[]}){if(!Array.isArray(t)||!t.length)throw new TypeError("createResolver needs at least one shared class");let s=new Map;for(let r of t)Et(r),s.set(r.subject,r);let e=new Map;for(let r of o){if(!r||typeof r.from!="string"||typeof r.to!="string")throw new TypeError("a lens needs from and to class subjects");if(typeof r.read!="function")throw new TypeError(`the lens from ${r.from} needs a read function`);if(!s.has(r.to))throw new Error(`the lens from ${r.from} maps to ${r.to}, which this resolver does not render`);if(s.has(r.from))throw new Error(`${r.from} is a shared class this resolver renders; it needs no lens`);if(e.has(r.from))throw new Error(`two lenses map from ${r.from}`);e.set(r.from,r)}let n=r=>{if(s.has(r))return{kind:"shared",class:s.get(r)};let p=e.get(r);return p?{kind:"lens",class:s.get(p.to),lens:p}:null},a=r=>{let p=n(r);if(!p)throw new Error(`${r} is not a class this view renders, and no lens maps it`);return p},c=r=>[...r.requires,...r.recommends];return{classes:[...s.keys()],match:n,accepts:r=>n(r)!==null,read(r,p){let l=a(p),i=l.kind==="lens"?l.lens.read(r):r;if(!i||typeof i!="object")throw new TypeError(`the lens from ${p} returned no row`);let m={};for(let y of c(l.class))ot(i[y])&&(m[y]=i[y]);let f=l.class.requires.filter(y=>!ot(m[y]));return{class:l.class.subject,via:l.kind,values:m,missing:f,complete:f.length===0}},write(r,p,l={}){let i=a(p),m=new Set(c(i.class)),f=Object.keys(r).filter(y=>!m.has(y));if(f.length)throw new Error(`${f.join(", ")} ${f.length===1?"is":"are"} not a field of ${i.class.subject}`);if(i.kind==="shared")return{...r};if(typeof i.lens.write!="function")throw new Error(`the lens from ${p} is read-only`);return i.lens.write(r,l)}}}var O={ATOMIC_URL:"https://atomicdata.dev/datatypes/atomicURL",BOOLEAN:"https://atomicdata.dev/datatypes/boolean",DATE:"https://atomicdata.dev/datatypes/date",FLOAT:"https://atomicdata.dev/datatypes/float",INTEGER:"https://atomicdata.dev/datatypes/integer",JSON:"https://atomicdata.dev/datatypes/json",MARKDOWN:"https://atomicdata.dev/datatypes/markdown",RESOURCEARRAY:"https://atomicdata.dev/datatypes/resourceArray",SLUG:"https://atomicdata.dev/datatypes/slug",STRING:"https://atomicdata.dev/datatypes/string",TIMESTAMP:"https://atomicdata.dev/datatypes/timestamp",UNKNOWN:"unknown-datatype"};var g={done:"done",dueDay:"due-day",priorityLabel:"priority-label",presence:"presence",lastSeen:"last-seen"},U=["active","completed","deleted","unavailable","unconfirmed"],A="todoist",$t={1:"Normal",2:"Medium",3:"High",4:"Urgent"},Dt=/^\d{4}-\d{2}-\d{2}/;function Nt(t){if(t.platform!==A)return t;let o=t.ontology.terms.find(n=>n.kind==="class"&&n.shortname==="task");if(!o)return t;let e=[[g.done,O.BOOLEAN,"Whether the task is completed in Todoist."],[g.dueDay,O.DATE,"The day the task is due, from Todoist's due date or time."],[g.priorityLabel,O.STRING,"Todoist priority: Normal, Medium, High or Urgent."],[g.presence,O.STRING,"Where the task stands in Todoist: active, completed, deleted, unavailable (gone, reason unknown) or unconfirmed (last known values)."],[g.lastSeen,O.STRING,"When Todoist last returned this task, as an ISO 8601 date and time."]].map(([n,a,c])=>({path:`urn:atomic:todoist:${n}`,kind:"property",shortname:n,datatype:a,description:c,requires:[],recommends:[]}));if(t.ontology.terms.some(n=>e.some(a=>a.shortname===n.shortname)))throw new Error("Todoist projection property collides with provider ontology");return{...t,ontology:{...t.ontology,terms:[...t.ontology.terms.map(n=>n===o?{...n,recommends:[...n.recommends,...e.map(a=>a.path)]}:n),...e]},records:t.records.map(nt)}}function nt(t){if(t.resource!=="task")return t;let o={...t.values,[g.done]:t.values.checked===!0,[g.presence]:t.values.checked===!0?"completed":"active"},s=rt(t.values.due),e=typeof s.date=="string"?s.date:s.datetime;typeof e=="string"&&Dt.test(e)&&(o[g.dueDay]=e.slice(0,10));let n=typeof t.values.priority=="number"?$t[t.values.priority]:void 0;n&&(o[g.priorityLabel]=n);let a=typeof t.values.content=="string"?t.values.content.trim():"";return{...t,name:a||t.name,values:o}}function rt(t){return t&&typeof t=="object"&&!Array.isArray(t)?t:{}}var It=["completed","deleted","unavailable"],J=t=>{let o=t.values[g.presence];return U.includes(o)?o:"active"},at=t=>!t.errors?.length;function q(t,o){if(o.platform!==A||!at(o))return[];let s=new Set(o.records.filter(e=>e.resource==="task").map(e=>e.id));return t.filter(e=>e.resource==="task"&&!s.has(e.id)&&!It.includes(J(e))).map(e=>e.id)}function it({previous:t,fetched:o,lookups:s=[],seenAt:e}){if(!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(e))throw new Error("seenAt must be an ISO 8601 date and time");let n=Nt(o),a=new Map(t.filter(d=>d.resource==="task").map(d=>[d.id,d])),c=new Map(s.map(d=>[d.id,d])),r=0,p=n.records.map(d=>{if(d.resource!=="task")return d;let u=a.get(d.id);return u&&J(u)!=="active"&&r++,{...d,values:{...d.values,[g.lastSeen]:e}}}),l=new Set(p.filter(d=>d.resource==="task").map(d=>d.id)),i=new Set(q(t,o)),m=[...a.values()].filter(d=>!l.has(d.id)).map(d=>{if(!i.has(d.id))return d;let u=v=>({...d,values:{...d.values,[g.presence]:v}}),h=c.get(d.id);if(!h||"error"in h)return u("unconfirmed");if(h.status===404)return u("unavailable");let T=rt(h.body);if(h.status!==200||T.id!==d.id)return u("unconfirmed");if(T.is_deleted===!0)return u("deleted");let k=nt({...d,values:T});return{...k,values:{...k.values,[g.lastSeen]:e}}}),f=[...p,...m],y={active:0,completed:0,deleted:0,unavailable:0,unconfirmed:0,reappeared:r,complete:at(o)};for(let d of f)d.resource==="task"&&y[J(d)]++;return{platform:{...n,records:f},summary:y}}var zt=200,Lt=50,$=class extends Error{constructor(s,e){super(s);this.status=e}status},ct=t=>!!t&&typeof t=="object"&&!Array.isArray(t);function Ft(t,o){if(t.status===401||t.status===403)throw new $(`Todoist refused ${o} (${t.status}); reconnect Todoist.`,t.status);if(t.status!==200)throw new $(`Todoist answered ${t.status} for ${o}.`,t.status);let s=t.body;if(!ct(s)||!Array.isArray(s.results))throw new $(`Todoist sent no results for ${o}.`);let e=s.next_cursor;return{rows:s.results.filter(ct),next:typeof e=="string"&&e?e:void 0}}async function pt(t,o,{pageSize:s=zt,maxPages:e=Lt}={}){let n=new Map,a;for(let c=1;;c++){if(c>e)return{rows:[...n.values()],partial:`Stopped reading ${o} after ${e} pages of ${s}; Todoist kept sending a next page.`};let r=new URLSearchParams({limit:String(s)});a&&r.set("cursor",a);let{rows:p,next:l}=Ft(await t(`${o}?${r}`),`${o.split("/").pop()} page ${c}`);for(let i of p)typeof i.id=="string"&&i.id&&n.set(i.id,i);if(!l)return{rows:[...n.values()]};a=l}}async function dt(t,o){let{rows:s}=await pt(t,"/api/v1/projects",o);return new Map(s.flatMap(e=>typeof e.id=="string"&&typeof e.name=="string"?[[e.id,e.name]]:[]))}async function lt(t,o){let{rows:s,partial:e}=await pt(t,"/api/v1/tasks",o),n=s.map(a=>({resource:"task",namespace:A,id:a.id,name:a.id,values:a}));return{platform:A,ontology:{description:"Todoist API v1, as the proxy serves it (read-only).",terms:[{path:"urn:atomic:todoist:task",kind:"class",shortname:"task",description:"An active task in the connected Todoist account.",datatype:O.STRING,requires:[],recommends:[]}]},records:n,...e?{errors:[e]}:{}}}async function ut(t,o){let s=[];for(let e of o)try{let n=await t(`/api/v1/tasks/${encodeURIComponent(e)}`);s.push({id:e,status:n.status,body:n.body})}catch(n){s.push({id:e,error:n instanceof Error?n.message:String(n)})}return s}var F=A,mt=st({classes:[N["issue-v1"]]});function yt(t,o){return async s=>{if(!s.startsWith("/api/v1/"))throw new Error(`Refusing a Todoist path: ${s}`);let e=await t.request({platform:o.platform,connectionId:o.connectionId,path:s,method:"GET"});return{status:e.status,body:e.body}}}var b=t=>typeof t=="string"&&t?t:void 0,Mt=(t,o)=>Array.isArray(t)||Array.isArray(o)?JSON.stringify(t)===JSON.stringify(o):t===o;async function _t(t,o,s){let{taskId:e,source:n}=o.properties,a=[],c=new Map;for(let r of await t.query({property:z,value:o.table})){let p=await t.getResource(r),l=b(p.get(e));if(!l||c.has(l))continue;c.set(l,p);let i={};try{let y=JSON.parse(b(p.get(n))??"{}");y&&typeof y=="object"&&!Array.isArray(y)&&(i=y)}catch{}let m=i[g.presence];(!U.includes(m)||m==="active")&&s&&i[g.lastSeen]===void 0&&(i={...i,[g.lastSeen]:s}),a.push({resource:"task",namespace:F,id:l,name:b(p.get(P))??l,values:i})}return{previous:a,rows:c}}function Vt(t,o,s){let e=o.properties,n=t.values,a=n[g.presence],c=a==="active",r={[P]:t.name,[V]:[n[g.done]===!0?G:Z]},p=[],l=b(n.description);l?r[C]=l:p.push(C);let i=b(n[g.dueDay]);i?r[L]=i:p.push(L);let m=mt.write(r,R);m[e.taskId]=t.id,m[e.presence]=a;let f=[[e.lastSeen,c?void 0:b(n[g.lastSeen])],[e.priority,b(n[g.priorityLabel])],[e.project,s.get(b(n.project_id)??"")]];for(let[u,h]of f)h===void 0?p.push(u):m[u]=h;let{[g.lastSeen]:y,...d}=n;return m[e.source]=JSON.stringify(c?d:{...d,[g.lastSeen]:y}),{set:m,unset:p}}async function gt(t,o,s,{now:e=()=>new Date().toISOString(),read:n}={}){let a=await dt(o,n),c=await lt(o,n),{previous:r,rows:p}=await _t(t,s,await tt(t,s)),l=q(r,c),i=await ut(o,l),m=e(),{platform:f,summary:y}=it({previous:r,fetched:c,lookups:i,seenAt:m}),d={total:0,added:0,updated:0,unchanged:0,presence:{active:y.active,completed:y.completed,deleted:y.deleted,unavailable:y.unavailable,unconfirmed:y.unconfirmed},reappeared:y.reappeared,checked:i.length,complete:y.complete};for(let u of f.records){if(u.resource!=="task")continue;d.total++;let{set:h,unset:T}=Vt(u,s,a),k=p.get(u.id);if(!k){await t.newResource({parent:s.table,isA:[s.rowClass],propVals:h}),d.added++;continue}let v=Object.entries(h).filter(([S,M])=>!Mt(k.get(S),M)),D=T.filter(S=>k.get(S)!==void 0);if(!v.length&&!D.length){d.unchanged++;continue}for(let[S,M]of v)k.set(S,M);for(let S of D)k.remove(S);await k.save(),d.updated++}return y.complete&&await et(t,s,m),d}async function ft(t,o){let s=o.properties,e=[];for(let n of await t.query({property:z,value:o.table})){let a=await t.getResource(n),c=b(a.get(s.taskId));if(!c)continue;let{values:r}=mt.read(a.props,R),p=r[V],l={dueDay:b(r[L]),priority:b(a.get(s.priority)),project:b(a.get(s.project)),lastSeen:b(a.get(s.lastSeen))};e.push({subject:n,taskId:c,name:b(r[P])??c,done:Array.isArray(p)&&p.includes(G),presence:b(a.get(s.presence))??"active",...Object.fromEntries(Object.entries(l).filter(([,i])=>i!==void 0))})}return e.sort((n,a)=>n.name.localeCompare(a.name))}var Ct={completed:"completed",deleted:"deleted",unavailable:"unavailable",unconfirmed:"unconfirmed"};function Gt(t){let o=`${t.total} task${t.total===1?"":"s"} (${t.added} added, ${t.updated} updated, ${t.unchanged} unchanged)`,s=[`${t.presence.active} active`];for(let[n,a]of Object.entries(Ct)){let c=t.presence[n];c&&s.push(`${c} ${a}`)}let e=t.complete?"":" The read was partial, so no missing task was checked.";return`${o}; ${s.join(", ")}.${e}`}function ht(t){switch(t.kind){case"loading":return"Loading\u2026";case"no-relay":return"This host cannot reach the integration proxy for apps yet.";case"other-table":return"This is another Issue table. The Todoist app imports only into its own table.";case"disconnected":return"Not connected. Connect Todoist to import your active tasks (read-only).";case"connecting":return"Waiting for you to confirm the connection\u2026";case"syncing":return"Importing tasks\u2026";case"synced":return`Last synced ${t.at.toLocaleTimeString()}: ${Gt(t.summary)}`;case"error":return`Refresh failed: ${t.message} Tasks imported earlier are kept.`}}var W=t=>t instanceof Error?t.message:String(t);function bt(t,o,s={}){let e={kind:"loading"},n,a=i=>{e=i,o(e)},c=()=>"tasks"in e?e.tasks:[],r=async()=>{if(n)return n;try{n=await Q(t)}catch(i){i instanceof x?a({kind:"other-table"}):a({kind:"error",message:W(i),tasks:c()});return}return n},p=async()=>n?ft(t,n).catch(()=>c()):c(),l={state:()=>e,async load(){let i=t.proxy;if(!i)return a({kind:"no-relay"}),{};if(!await r())return{};let m=await p(),[f]=await i.connections({platform:F});return f?{syncing:l.sync(f)}:(a({kind:"disconnected",tasks:m}),{})},async connect(){let i=t.proxy;if(!i)return a({kind:"no-relay"});a({kind:"connecting",tasks:c()});try{let m=await i.connect({platform:F});m.status==="connected"?await l.sync(m):a({kind:"disconnected",tasks:c()})}catch(m){a({kind:"error",message:W(m),tasks:c()})}},async sync(i="connection"in e?e.connection:void 0){let m=t.proxy;if(!m)return a({kind:"no-relay"});if(!i||e.kind==="syncing")return;let f=await r();if(f){a({kind:"syncing",connection:i,tasks:c()});try{let y=await gt(t,yt(m,i),f,s);a({kind:"synced",connection:i,at:new Date,summary:y,tasks:await p()})}catch(y){a({kind:"error",connection:i,message:W(y),tasks:await p()})}}}};return l}var kt=[["Task",t=>t.name],["Status",t=>t.done?"Done":"Todo"],["Presence",t=>t.presence],["Due",t=>t.dueDay??""],["Priority",t=>t.priority??""],["Project",t=>t.project??""],["Last seen",t=>t.lastSeen??""]];async function le({root:t,store:o}){let s=t.ownerDocument,e=(u,h="")=>{let T=s.createElement(u);return T.textContent=h,T},n=e("h1","Todoist"),a=e("p");a.setAttribute("role","status");let c=e("button","Connect Todoist"),r=e("button","Sync now");for(let u of[c,r])u.type="button";let p=e("p","Read-only: closing or editing a task here is not sent to Todoist. A task that stops appearing is checked by id and shown as completed only when Todoist says so."),l=e("table"),i=e("thead"),m=e("tr");for(let[u]of kt)m.append(e("th",u));i.append(m);let f=e("tbody");l.append(i,f),l.setAttribute("aria-label","Imported tasks"),t.style.fontFamily="system-ui, sans-serif",t.style.padding="1rem",l.style.borderCollapse="collapse",l.style.marginTop="1rem",t.replaceChildren(n,a,c,r,p,l);let y=u=>{a.textContent=ht(u),c.hidden=!(u.kind==="disconnected"||u.kind==="error"&&!u.connection);let h=u.kind==="synced"||u.kind==="syncing"||u.kind==="error"&&!!u.connection;r.hidden=!h,r.disabled=u.kind==="syncing";let T="tasks"in u?u.tasks:[];l.hidden=T.length===0,f.replaceChildren(...T.map(k=>{let v=e("tr");v.dataset.task=k.taskId,v.dataset.subject=k.subject,v.dataset.presence=k.presence;for(let[,D]of kt){let S=e("td",D(k));S.style.padding="0.25rem 0.75rem 0.25rem 0",v.append(S)}return v}))},d=bt(o,y);y(d.state()),c.addEventListener("click",()=>{d.connect()}),r.addEventListener("click",()=>{d.sync()}),await d.load().catch(u=>{a.textContent=`Could not load: ${u instanceof Error?u.message:String(u)}`})}export{le as view}; diff --git a/docs/design/bundles.md b/docs/design/bundles.md index 1882fd662..c16dc1c90 100644 --- a/docs/design/bundles.md +++ b/docs/design/bundles.md @@ -74,7 +74,7 @@ copy or code without host evidence, as in [READINESS.md](../integrations/READINE | Bundle | Row class(es) | Views | Reflectors | Importers | Lenses (planned) | Folder today | Catalog entries today | | ------------ | ---------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------- | -------------------------------------------- | ------------------------------------------------- | ---------------------------------------- | | **Calendar** | `event-v1` | `calendar/app/`; built-in Calendar | Google Calendar (`calendar/devonian/google-calendar/`) | – | – | `calendar/` | `devonian-google-calendar` | -| **Issues** | `issue-v1` | `issue-tracker/app/`; built-in Issues | GitHub (`issue-tracker/devonian/github-issues/`), Todoist (read) | – | Issue Tracker template → `issue-v1` | `issue-tracker/` | `devonian-todoist` (GitHub has none) | +| **Issues** | `issue-v1` | `issue-tracker/app/`; built-in Issues | GitHub (`issue-tracker/devonian/github-issues/`), Todoist (read) | – | Issue Tracker template → `issue-v1` | `issue-tracker/` | `todoist` (GitHub has none) | | **Time** | `time-entry-v1` (+ `work-project-v1`, `work-person-v1`) | `timesheets/app/`; built-in Timer | Clockify (`timesheets/devonian/clockify/`), read | – | Time tracker template → `time-entry-v1` | `timesheets/` | `timesheets` | | **Money** | `bank-transaction-v1` | `money/app/` | Moneybird (declared only) | MT940 and camt.053 (`money/plugin.ts`) | – | `money/` | `money`, `moneybird` | | **Tables** | Per data source (no shared class) | Built-in table view | Notion (`notion/app/`, `notion/plugin.ts`) | – | – | `notion/` | `notion` | @@ -97,7 +97,7 @@ Notes: endpoints (placements C, D, E), not table sync or views. Q1 asks whether they get a part kind of their own (`route`) or stay outside this model. - A bundle may list a reflector with no host entry point yet, as today's - catalog lists `devonian-todoist`. The bundle's card must then say which + catalog listed `devonian-todoist` until the Todoist drive app hosted it. The bundle's card must then say which parts work, per the "declared, not verified" rule. ## 3. Catalog shape diff --git a/integrations/READINESS.md b/integrations/READINESS.md index bcedce11c..4ba7391d7 100644 --- a/integrations/READINESS.md +++ b/integrations/READINESS.md @@ -74,21 +74,21 @@ read from the atomic-server source at the pin. ## Matrix -| Plugin (catalog id) | Runtime of the current code | Install entry point at the pin | Import / write scope (declared) | Evidence | Open blockers | -| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Pets, drive app (`pets`) | Drive app `pets/app/`: iframe, `syncables/browser` over `store.proxy` | Integrations → Show experimental plugins → Drive apps → Install (`pets` 0.1.1, from GitHub Pages, integrity-checked). The host E2E installs this way, then updates from an older recorded version | Read-only. Pets from the mock `pets` platform into the app's own table | Unit; **Host E2E** (`pets` lane: catalog install and update, connect, 5 rows, datatypes) | None filed | -| Pets, static demo (`pets`) | Sandbox `pets/plugin.js`, no network | None. Its setup dialog was removed in `4bab16ee6` | Five static pets into a Pets table | Unit; `certify.mjs --layer js`. Historical: Rust sandbox test (removed from atomic-server in `4bab16ee6`) | None filed; the catalog card still describes this demo, not the drive app | -| Notion, drive app (`notion`) | Drive app `notion/app/`: iframe, `syncables/browser` + Devonian `AtomicLens` over `store.proxy`; the #89 UI (table, board and list views, side peek, sync details, Disconnect), and since 0.2.0 "Review changes" (compare on open, review, send) | Published (`notion` 0.2.0 on GitHub Pages) but `enabled: false` pending launch, so Drive apps does not offer it. The host E2E installs it through Drive apps, with the lanes' dev-server serving the entry enabled | Every shared data source into one table; plain fields and select/status/multi-select options. Two-way for those fields on existing pages, after review (`PATCH /v1/pages/{id}`, baseline on the row); no page creation, no deletes | Unit; **Host E2E** (`notion` lane: catalog install, connect, 3 rows, column datatypes, formatted-text warning, the #89 states against the fixture's scenarios, an edit made in the host found on open and sent, a conflict resolved). No live run | [#8](https://github.com/ontola/atomic-plugins/issues/8) live evidence for writes; page creation; #177 Q9 (sync-status view only) | -| Notion, two-way pilot (no card; shares `notion`'s version) | Sandbox `notion/plugin.js` | None. `ConnectNotion` was removed in `4bab16ee6`. The `notion` catalog card now describes the drive app | Two-way on one data source: plain fields, property names, table/board view subset (`package.json` capabilities) | Unit; `certify.mjs --layer js`; `live` tier runs the installer against the pinned server with Notion stubbed. Historical: live UI import and title edits via `ConnectNotion` | Retire once the drive app's writes (0.2.0) have live evidence ([#8](https://github.com/ontola/atomic-plugins/issues/8)) | -| Clockify (`timesheets`) | Drive app `timesheets/app/`: iframe, own Clockify client over `store.proxy.request`. The #89 UI (week grid, entries, projects, read-only drawer, settings) over the #123 M1 observation log and M2 timeline | Published (`timesheets` 0.1.0 on GitHub Pages) but `enabled: false` pending launch, so Drive apps does not offer it. The host E2E installs it through Drive apps, with the lanes' dev-server serving the entry enabled | Read-only. The user's own entries in one workspace, rolling 7- or 30-day look-back; completed entries as rows. Conflicts and not-loaded time shown read-only. No writes to Clockify yet | Unit (fake store; #123 M1 scenarios and fold property tests, M2 timeline incl. DST days); **Host E2E** (`timesheets` lane: catalog install, connect, setup, import, reload, changed entry, 7 → 30 days, 503 recovery, an M2 conflict and unknown time). The mock's Clockify endpoints follow API behaviour checked against a live account on 2026-09-24 (#123); the app itself has no live run | [#123](https://github.com/ontola/atomic-plugins/issues/123) M3/M4 (writes, resolving conflicts), [#97](https://github.com/ontola/atomic-plugins/issues/97) | -| Bank statements, importer (`money`) | Sandbox `money/plugin.js` (0.3.0), file handed over as `ctx.upload`, no network | Draft from a published release (Integrations → Community plugins → Create draft), then Set up and Import on the plugin page (atomic-server#1653's `accepts`/`destination`, in the pin). Publishing the bundle to a server is manual (#94). An importer set up before 0.3.0's `tables` pauses until Set up runs again | Import only. MT940 ≤ 512 KB, camt.053 ≤ 5 MB, ≤ 500 transactions per file, into Bank transactions plus one Imported statements row per statement (`destination.tables`, atomic-server#1768) | Unit; `certify.mjs --layer js`; host E2E `money/e2e/money.spec.ts` (synthetic MT940/camt.053: import with its statement row, reload, reimport, local edit, conflict, refused files). Historical: a real 272-transaction bunq MT940 export through `ImportMT940` (2026-09-11) | [#94](https://github.com/ontola/atomic-plugins/issues/94) | -| Money, drive app (`money`) | Drive app `money/app/`: iframe, a view of the importer's table (`store.getData()`), no `store.proxy`; imports through the importer (`store.importer.run`, atomic-server#1774) | Published (`money` 0.3.0 on GitHub Pages) but `enabled: false`. A catalog Install would not give a working app yet: it gets its own empty table with no importer, and the importer's table offers under Add view only apps rendering its class. The host E2E installs test-side and adds the Bank transaction class to the app's `renders` | Reads the importer's Bank transactions and Imported statements tables. Writes only `money-category` and `money-note` on a row, after the person allows row editing (atomic-server#1788) | Unit (fake store modelling a current and an older host); axe and screenshots (`app/harness/`); **Host E2E** (`money` lane, second test: Add view, import through the host's review, closing balance, category after Allow editing, in-app check). At pin `2567fc30b` the second test could fail on atomic-server#1846 ('New app' missing); fixed at pin `1432e244a`, where both tests passed once on 2026-09-29 | Install path above; [#179](https://github.com/ontola/atomic-plugins/pull/179) pin | -| Willow drop (`willow-drop`) | Sandbox `willow-drop/plugin.js`, drop file handed over as `ctx.upload` text and turned back into bytes, no network | As for Bank statements: draft from a published release, then Set up and Import on the plugin page. Publishing is manual (#94) | Import only. Willow'25 drops up to 5,000,000 bytes and 1,000 entries (declared); no delegated capabilities, no partial payloads | Unit (fixtures written by willow25 0.7.9); host E2E `willow-drop/e2e/willow-drop.spec.ts` (raw and base64 upload, reimport, refused drops) | [#139](https://github.com/ontola/atomic-plugins/issues/139) follow-ups: delegations, partial payloads | -| remoteStorage server (`remotestorage`) | Sandbox `remotestorage/plugin.js` as plugin routes (QuickJS) on the installation's own origin: WebFinger, OAuth through the host's consent page, `/storage` with blob bodies; also a text importer | Only on a server built with the `plugin-routes` feature at `--plugin-routes read-write` with a routes origin, at atomic-server candidate15 or later (the pin, candidate19 `a12b74a`, qualifies): publish a release, then Install from the Integrations page's review with the route-write grant. Catalog entry `enabled: false`. atomic.place builds without the feature | Files (with blobs) only under the folder named in `config.table`, created by the installation; bearer tokens per category, `r` or `rw` (declared) | Unit (`plugin.test.mjs`, in-memory `ctx`); host E2E `remotestorage/e2e/server.spec.ts` (remotestorage.js 2.0.0-beta.10 connects, writes, reads, lists, deletes) and `import.spec.ts`, passing at the pin on 2026-10-01; opt-in `api-suite.spec.ts`: remotestorage/api-test-suite 46 of 53 at the pin, the 7 failures host gaps (README) | [#167](https://github.com/ontola/atomic-plugins/issues/167) §1 in-commit preconditions, §2 blob cleanup, §3 empty `Authorization` on `authOptional`, §4 per-route OPTIONS, compression, `Content-Range` | -| Google Calendar (`calendar`) | Drive app `calendar/app/`: iframe, `calendar/adapter.ts` through `app/relay.ts` over `store.proxy`. The #89 UI (agenda, week, drawer, review sheet; Month hands off to the table's Calendar view, which spans all-day ranges because rows use the host's `atomic-calendar-*` field names; from 0.2.0 the rows are the shared `event-v1` class of #177, and the app is offered under Add view on any `event-v1` table, where it shows the rows read only) | Published (`calendar` 0.2.0 committed for GitHub Pages; 0.1.0 wrote `day`/`all-day` and no end day; 0.1.4 removed the adapter's unused sandbox manifest and credential placeholder, and the relay enforces the declared scope of `app/operations.ts`; 0.2.0 moves an older install's table onto `event-v1` on first open) but `enabled: false` pending launch and the stable ontology domain, so Drive apps does not offer it. The host E2E installs it through Drive apps, with the lanes' dev-server serving the entry enabled | One calendar's single non-recurring events in (≤ 25,000 per scan); reviewed edits of five fields out with If-Match and `sendUpdates=none`; no creates or deletes in Google | Unit; **Host E2E** (`calendar` lane: catalog install, connect, import, refresh after a Google-side edit, review and send, 412 conflict, lost response, links/Month/Disconnect through the host, the host Calendar view spanning a three-day all-day event and placing a timed one, responsive and theme, the app as a view of a hand-made `event-v1` table; needs network access to the published ontology on GitHub Pages). Historical: live import (2026-09-09, proxy v39) through the retired LocalThought snapshot importer. No live run of the drive app | [#101](https://github.com/ontola/atomic-plugins/issues/101) live verification | -| Todoist (`devonian-todoist`) | Library only: `issue-tracker/todoist.ts` projection | None. Its host hook was removed in `f3efedf65` | Declared: read-only, active tasks and projects | Unit. Recorded-fixture tests skip until a recording exists | [#99](https://github.com/ontola/atomic-plugins/issues/99), [#46](https://github.com/ontola/atomic-plugins/issues/46) | -| GitHub issues (`issue-tracker`) | Drive app `issue-tracker/app/`: iframe, the Devonian bridge from `issue-tracker/devonian/github-issues/` (npm `devonian` 0.8.0) over `store.proxy`. The #89 board/list UI. The lens's sandbox `plugin.ts` has no host | Published (`issue-tracker` 0.1.1 on GitHub Pages; #206) but `enabled: false` pending launch, so Drive apps does not offer it. The host E2E installs it through Drive apps, with the lanes' dev-server serving the entry enabled | Two-way for one repository: title, body, Todo/Doing/Done status, comments. Every GitHub write is held for review before send. An issue gone from GitHub: "Keep here only" or "Remove from board". An uncertain create has no in-app way out yet | Unit (incl. state 13); **Host E2E** (`issue-tracker` lane: catalog install, connect, repository picker, import, reload, reviewed status update, conflict review, keyboard move, comment). Opt-in lens `*.live.test.ts` (need `GITHUB_TOKEN`; not run in CI). Historical: live GitHub read (2026-09-09, proxy v38) via the retired server flow. No live run of the drive app | [#156](https://github.com/ontola/atomic-plugins/issues/156) "It landed", [#100](https://github.com/ontola/atomic-plugins/issues/100) | -| Moneybird (`moneybird`) | Drive app `money/moneybird/`: iframe, own Moneybird reader over `store.proxy.request` (contacts only) | Catalog Drive apps install of `apps/moneybird/0.1.0/ui.js`; the entry stays `enabled: false`, so only the lanes' dev-server offers it | Read-only. Contacts of one administration into a typed table | Unit; **Host E2E** on a SYNTHETIC fixture (`money` lane, `moneybird.spec.ts`: catalog install, connect, choose an administration, 5 typed rows, failed refresh keeps rows, resync). Nothing verified against real Moneybird | [#102](https://github.com/ontola/atomic-plugins/issues/102) (a real recording needs a Moneybird account) | +| Plugin (catalog id) | Runtime of the current code | Install entry point at the pin | Import / write scope (declared) | Evidence | Open blockers | +| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Pets, drive app (`pets`) | Drive app `pets/app/`: iframe, `syncables/browser` over `store.proxy` | Integrations → Show experimental plugins → Drive apps → Install (`pets` 0.1.1, from GitHub Pages, integrity-checked). The host E2E installs this way, then updates from an older recorded version | Read-only. Pets from the mock `pets` platform into the app's own table | Unit; **Host E2E** (`pets` lane: catalog install and update, connect, 5 rows, datatypes) | None filed | +| Pets, static demo (`pets`) | Sandbox `pets/plugin.js`, no network | None. Its setup dialog was removed in `4bab16ee6` | Five static pets into a Pets table | Unit; `certify.mjs --layer js`. Historical: Rust sandbox test (removed from atomic-server in `4bab16ee6`) | None filed; the catalog card still describes this demo, not the drive app | +| Notion, drive app (`notion`) | Drive app `notion/app/`: iframe, `syncables/browser` + Devonian `AtomicLens` over `store.proxy`; the #89 UI (table, board and list views, side peek, sync details, Disconnect), and since 0.2.0 "Review changes" (compare on open, review, send) | Published (`notion` 0.2.0 on GitHub Pages) but `enabled: false` pending launch, so Drive apps does not offer it. The host E2E installs it through Drive apps, with the lanes' dev-server serving the entry enabled | Every shared data source into one table; plain fields and select/status/multi-select options. Two-way for those fields on existing pages, after review (`PATCH /v1/pages/{id}`, baseline on the row); no page creation, no deletes | Unit; **Host E2E** (`notion` lane: catalog install, connect, 3 rows, column datatypes, formatted-text warning, the #89 states against the fixture's scenarios, an edit made in the host found on open and sent, a conflict resolved). No live run | [#8](https://github.com/ontola/atomic-plugins/issues/8) live evidence for writes; page creation; #177 Q9 (sync-status view only) | +| Notion, two-way pilot (no card; shares `notion`'s version) | Sandbox `notion/plugin.js` | None. `ConnectNotion` was removed in `4bab16ee6`. The `notion` catalog card now describes the drive app | Two-way on one data source: plain fields, property names, table/board view subset (`package.json` capabilities) | Unit; `certify.mjs --layer js`; `live` tier runs the installer against the pinned server with Notion stubbed. Historical: live UI import and title edits via `ConnectNotion` | Retire once the drive app's writes (0.2.0) have live evidence ([#8](https://github.com/ontola/atomic-plugins/issues/8)) | +| Clockify (`timesheets`) | Drive app `timesheets/app/`: iframe, own Clockify client over `store.proxy.request`. The #89 UI (week grid, entries, projects, read-only drawer, settings) over the #123 M1 observation log and M2 timeline | Published (`timesheets` 0.1.0 on GitHub Pages) but `enabled: false` pending launch, so Drive apps does not offer it. The host E2E installs it through Drive apps, with the lanes' dev-server serving the entry enabled | Read-only. The user's own entries in one workspace, rolling 7- or 30-day look-back; completed entries as rows. Conflicts and not-loaded time shown read-only. No writes to Clockify yet | Unit (fake store; #123 M1 scenarios and fold property tests, M2 timeline incl. DST days); **Host E2E** (`timesheets` lane: catalog install, connect, setup, import, reload, changed entry, 7 → 30 days, 503 recovery, an M2 conflict and unknown time). The mock's Clockify endpoints follow API behaviour checked against a live account on 2026-09-24 (#123); the app itself has no live run | [#123](https://github.com/ontola/atomic-plugins/issues/123) M3/M4 (writes, resolving conflicts), [#97](https://github.com/ontola/atomic-plugins/issues/97) | +| Bank statements, importer (`money`) | Sandbox `money/plugin.js` (0.3.0), file handed over as `ctx.upload`, no network | Draft from a published release (Integrations → Community plugins → Create draft), then Set up and Import on the plugin page (atomic-server#1653's `accepts`/`destination`, in the pin). Publishing the bundle to a server is manual (#94). An importer set up before 0.3.0's `tables` pauses until Set up runs again | Import only. MT940 ≤ 512 KB, camt.053 ≤ 5 MB, ≤ 500 transactions per file, into Bank transactions plus one Imported statements row per statement (`destination.tables`, atomic-server#1768) | Unit; `certify.mjs --layer js`; host E2E `money/e2e/money.spec.ts` (synthetic MT940/camt.053: import with its statement row, reload, reimport, local edit, conflict, refused files). Historical: a real 272-transaction bunq MT940 export through `ImportMT940` (2026-09-11) | [#94](https://github.com/ontola/atomic-plugins/issues/94) | +| Money, drive app (`money`) | Drive app `money/app/`: iframe, a view of the importer's table (`store.getData()`), no `store.proxy`; imports through the importer (`store.importer.run`, atomic-server#1774) | Published (`money` 0.3.0 on GitHub Pages) but `enabled: false`. A catalog Install would not give a working app yet: it gets its own empty table with no importer, and the importer's table offers under Add view only apps rendering its class. The host E2E installs test-side and adds the Bank transaction class to the app's `renders` | Reads the importer's Bank transactions and Imported statements tables. Writes only `money-category` and `money-note` on a row, after the person allows row editing (atomic-server#1788) | Unit (fake store modelling a current and an older host); axe and screenshots (`app/harness/`); **Host E2E** (`money` lane, second test: Add view, import through the host's review, closing balance, category after Allow editing, in-app check). At pin `2567fc30b` the second test could fail on atomic-server#1846 ('New app' missing); fixed at pin `1432e244a`, where both tests passed once on 2026-09-29 | Install path above; [#179](https://github.com/ontola/atomic-plugins/pull/179) pin | +| Willow drop (`willow-drop`) | Sandbox `willow-drop/plugin.js`, drop file handed over as `ctx.upload` text and turned back into bytes, no network | As for Bank statements: draft from a published release, then Set up and Import on the plugin page. Publishing is manual (#94) | Import only. Willow'25 drops up to 5,000,000 bytes and 1,000 entries (declared); no delegated capabilities, no partial payloads | Unit (fixtures written by willow25 0.7.9); host E2E `willow-drop/e2e/willow-drop.spec.ts` (raw and base64 upload, reimport, refused drops) | [#139](https://github.com/ontola/atomic-plugins/issues/139) follow-ups: delegations, partial payloads | +| remoteStorage server (`remotestorage`) | Sandbox `remotestorage/plugin.js` as plugin routes (QuickJS) on the installation's own origin: WebFinger, OAuth through the host's consent page, `/storage` with blob bodies; also a text importer | Only on a server built with the `plugin-routes` feature at `--plugin-routes read-write` with a routes origin, at atomic-server candidate15 or later (the pin, candidate19 `a12b74a`, qualifies): publish a release, then Install from the Integrations page's review with the route-write grant. Catalog entry `enabled: false`. atomic.place builds without the feature | Files (with blobs) only under the folder named in `config.table`, created by the installation; bearer tokens per category, `r` or `rw` (declared) | Unit (`plugin.test.mjs`, in-memory `ctx`); host E2E `remotestorage/e2e/server.spec.ts` (remotestorage.js 2.0.0-beta.10 connects, writes, reads, lists, deletes) and `import.spec.ts`, passing at the pin on 2026-10-01; opt-in `api-suite.spec.ts`: remotestorage/api-test-suite 46 of 53 at the pin, the 7 failures host gaps (README) | [#167](https://github.com/ontola/atomic-plugins/issues/167) §1 in-commit preconditions, §2 blob cleanup, §3 empty `Authorization` on `authOptional`, §4 per-route OPTIONS, compression, `Content-Range` | +| Google Calendar (`calendar`) | Drive app `calendar/app/`: iframe, `calendar/adapter.ts` through `app/relay.ts` over `store.proxy`. The #89 UI (agenda, week, drawer, review sheet; Month hands off to the table's Calendar view, which spans all-day ranges because rows use the host's `atomic-calendar-*` field names; from 0.2.0 the rows are the shared `event-v1` class of #177, and the app is offered under Add view on any `event-v1` table, where it shows the rows read only) | Published (`calendar` 0.2.0 committed for GitHub Pages; 0.1.0 wrote `day`/`all-day` and no end day; 0.1.4 removed the adapter's unused sandbox manifest and credential placeholder, and the relay enforces the declared scope of `app/operations.ts`; 0.2.0 moves an older install's table onto `event-v1` on first open) but `enabled: false` pending launch and the stable ontology domain, so Drive apps does not offer it. The host E2E installs it through Drive apps, with the lanes' dev-server serving the entry enabled | One calendar's single non-recurring events in (≤ 25,000 per scan); reviewed edits of five fields out with If-Match and `sendUpdates=none`; no creates or deletes in Google | Unit; **Host E2E** (`calendar` lane: catalog install, connect, import, refresh after a Google-side edit, review and send, 412 conflict, lost response, links/Month/Disconnect through the host, the host Calendar view spanning a three-day all-day event and placing a timed one, responsive and theme, the app as a view of a hand-made `event-v1` table; needs network access to the published ontology on GitHub Pages). Historical: live import (2026-09-09, proxy v39) through the retired LocalThought snapshot importer. No live run of the drive app | [#101](https://github.com/ontola/atomic-plugins/issues/101) live verification | +| Todoist (`todoist`) | Drive app `issue-tracker/todoist-app/`: iframe, `issue-tracker/todoist.ts` (projection and the #99 disappearance check) over `store.proxy.request`, rows of the shared `issue-v1` class | Catalog Drive apps install of `apps/todoist/0.1.0/ui.js`; the entry stays `enabled: false` (shared ontology on github.io), so only the lanes' dev-server offers it | Read-only. Active tasks into an `issue-v1` table (title, task/v1 status, body, due date; priority, project, presence, last-seen as extras). A task gone from the active list is looked up by id once: completed closes it, deleted/unavailable/unconfirmed do not; a partial read settles nothing; no row removed | Unit; **Host E2E** on a SYNTHETIC fixture (`issue-tracker` lane, `todoist.spec.ts`: catalog install, connect, 5 `issue-v1` rows, a reload that writes no row, a task completed in Todoist turns up done, one made unreachable stays open as unavailable). Nothing verified against real Todoist, including what it answers by id for a completed task | [#99](https://github.com/ontola/atomic-plugins/issues/99), [#46](https://github.com/ontola/atomic-plugins/issues/46) (the recording replaces the synthetic rows) | +| GitHub issues (`issue-tracker`) | Drive app `issue-tracker/app/`: iframe, the Devonian bridge from `issue-tracker/devonian/github-issues/` (npm `devonian` 0.8.0) over `store.proxy`. The #89 board/list UI. The lens's sandbox `plugin.ts` has no host | Published (`issue-tracker` 0.1.1 on GitHub Pages; #206) but `enabled: false` pending launch, so Drive apps does not offer it. The host E2E installs it through Drive apps, with the lanes' dev-server serving the entry enabled | Two-way for one repository: title, body, Todo/Doing/Done status, comments. Every GitHub write is held for review before send. An issue gone from GitHub: "Keep here only" or "Remove from board". An uncertain create has no in-app way out yet | Unit (incl. state 13); **Host E2E** (`issue-tracker` lane: catalog install, connect, repository picker, import, reload, reviewed status update, conflict review, keyboard move, comment). Opt-in lens `*.live.test.ts` (need `GITHUB_TOKEN`; not run in CI). Historical: live GitHub read (2026-09-09, proxy v38) via the retired server flow. No live run of the drive app | [#156](https://github.com/ontola/atomic-plugins/issues/156) "It landed", [#100](https://github.com/ontola/atomic-plugins/issues/100) | +| Moneybird (`moneybird`) | Drive app `money/moneybird/`: iframe, own Moneybird reader over `store.proxy.request` (contacts only) | Catalog Drive apps install of `apps/moneybird/0.1.0/ui.js`; the entry stays `enabled: false`, so only the lanes' dev-server offers it | Read-only. Contacts of one administration into a typed table | Unit; **Host E2E** on a SYNTHETIC fixture (`money` lane, `moneybird.spec.ts`: catalog install, connect, choose an administration, 5 typed rows, failed refresh keeps rows, resync). Nothing verified against real Moneybird | [#102](https://github.com/ontola/atomic-plugins/issues/102) (a real recording needs a Moneybird account) | `integrations/localthought/` is shared tooling, not a user-facing plugin: the shared mock proxy every E2E lane uses (`mock-proxy.mjs`, which speaks diff --git a/integrations/catalog.json b/integrations/catalog.json index 891a826ef..e626c347f 100644 --- a/integrations/catalog.json +++ b/integrations/catalog.json @@ -162,22 +162,25 @@ "https://atomicdata.dev/integrations/properties/app-module-integrity": "sha384-YCh0XA/74ulx5QYL6uIXiCDI3oXaGSH2AzgurOivVp3kUZCTSx1pCwPzRu2ZfzIY" }, { - "https://atomicdata.dev/properties/localId": "devonian-todoist", + "https://atomicdata.dev/properties/localId": "todoist", "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/integrations/classes/PluginCatalogEntry" ], - "https://atomicdata.dev/properties/shortname": "devonian-todoist", + "https://atomicdata.dev/properties/shortname": "todoist", "https://atomicdata.dev/integrations/properties/experimental": true, "https://atomicdata.dev/integrations/properties/enabled": false, - "https://atomicdata.dev/properties/name": "Todoist (Devonian)", + "https://atomicdata.dev/properties/name": "Todoist", "https://atomicdata.dev/properties/emoji": "✅", - "https://atomicdata.dev/properties/description": "Bring your Todoist projects and tasks into a local issue tracker.", - "https://atomicdata.dev/integrations/properties/capabilities": "Imports active tasks and projects. Tasks open in the Issues view with their title, due day and priority. Todoist lists active tasks only, so a task shows as closed only when Todoist itself reports it checked.", - "https://atomicdata.dev/integrations/properties/events": "Was planned as: connect through the integration proxy, then Sync now (and every five minutes while the folder is open) to pull the latest tasks. The LocalThought connect dialog and sync panel that did this were removed from atomic-server, and no drive app wraps the Todoist lens yet, so nothing runs it at the pin.", - "https://atomicdata.dev/integrations/properties/limitation": "Read only: the proxy's Todoist access is data:read, so closing, editing or creating a task here is not sent to Todoist. A task that stops appearing is never assumed completed. The lens can check such a task by id and mark it completed, deleted, unavailable or unconfirmed, with when it was last seen, but no host runs that check yet, and nothing has been verified against a live Todoist account.", - "https://atomicdata.dev/integrations/properties/keywords": "todoist tasks todo projects devonian lens local tracker issues", - "https://atomicdata.dev/integrations/properties/requires-api-plugins": true, - "https://atomicdata.dev/integrations/properties/platform": "todoist" + "https://atomicdata.dev/properties/description": "Bring the active tasks of one Todoist account into an Issues table, read-only.", + "https://atomicdata.dev/integrations/properties/capabilities": "Imports the connected account's active tasks into the app's table as rows of the shared Issue class (issue-v1: title, task/v1 status, body and due date), with the Todoist priority, project, task id and presence as extra columns, so other views of that class can read them. A task that stops appearing in Todoist's active list is looked up by id once and marked completed, deleted, unavailable or unconfirmed, with when it was last seen; only completed closes it. No row is ever removed.", + "https://atomicdata.dev/integrations/properties/events": "Install from Drive apps and connect Todoist through the host's consent bar. Tasks refresh whenever the app is opened and on Sync now. Nothing runs while the app is closed.", + "https://atomicdata.dev/integrations/properties/limitation": "Read-only: the proxy's Todoist access is data:read, so closing, editing or creating a task here is not sent to Todoist, and a local edit to an imported column is overwritten at the next sync. Active tasks only: a task completed before the first import is never imported. A task gone from the active list is never assumed completed: when Todoist's by-id check answers 404 or fails, the row keeps its last known values and says so. Added as a view of another Issue table, the app imports nothing. One account per app. Waits for the stable ontology domain. Declared, and tested against a synthetic fixture only: not verified against a live Todoist account (#46), including what Todoist answers by id for a completed task.", + "https://atomicdata.dev/integrations/properties/keywords": "todoist tasks todo projects issues read-only drive app", + "https://atomicdata.dev/integrations/properties/version": "0.1.0", + "https://atomicdata.dev/integrations/properties/app-row-name": "Issue", + "https://atomicdata.dev/integrations/properties/app-row-name-plural": "Issues", + "https://atomicdata.dev/integrations/properties/app-module": "https://ontola.github.io/atomic-plugins/apps/todoist/0.1.0/ui.js", + "https://atomicdata.dev/integrations/properties/app-module-integrity": "sha384-KnALQ7jjJxz3vd4jnAIjq50twSKzF+piMq1rFeDk/xTl7En7y53QU2boOmDLZK/q" }, { "@id": "https://atomicdata.dev/integrations/catalog/money", diff --git a/integrations/issue-tracker/README.md b/integrations/issue-tracker/README.md index 4777db86c..1dd2f183c 100644 --- a/integrations/issue-tracker/README.md +++ b/integrations/issue-tracker/README.md @@ -11,7 +11,10 @@ This folder also holds the plugin's other issue sources: bridge (moved from the `devonian` package; see its README). - `todoist.ts`: the read-only LocalThought projection of Todoist tasks onto an issue list (moved from `integrations/localthought/`), with - `todoist.test.ts` and the recorded-fixture check `todoist-fixture.test.ts`. + `todoist.test.ts` and the fixture check `todoist-fixture.test.ts`. +- `todoist-app/`: the **Todoist drive app**, the host for `todoist.ts` + (#99's host journey). See [Todoist drive app](#todoist-drive-app-todoist-app) + below. ## Mapping @@ -71,13 +74,76 @@ check) is: `GET /tasks/{id}` with `checked: true`, rather than a 404, is not verified: there is no recorded fixture yet (#46) and no credentials here. If it answers 404, completed tasks will show as `unavailable`, which is still -not a false "completed". The cases above are covered by synthetic fixture -tests in `todoist.test.ts`. **No host calls `reconcileTodoistTasks` yet.** -Nothing in atomic-server at the pin (`bae5cdbe3`) imports `todoist.ts` at -all, neither the projection nor this check (searched `browser/` and -`server/src`), so the `devonian-todoist` catalog entry describes a flow no -host runs today. The host journey that runs the check, and exercises these -states end to end, is still to be built. +not a false "completed". The cases above are covered by synthetic tests in +`todoist.test.ts`, and the host that runs them is the Todoist drive app +below: `todoist-app/sync.ts` calls `absentTodoistTasks`, looks the absent +tasks up through the host's proxy client, and calls +`reconcileTodoistTasks`. `fixtures/todoist/` serves SYNTHETIC rows +(`synthetic.mjs`, hand-written from Todoist's API documentation) until #46 +records `api/`; its drivers model `completeTask` as "gone from `/tasks`, +`checked: true` by id", which is this fixture's assumption, not Todoist's +verified behaviour. + +## Todoist drive app (`todoist-app/`) + +An iframe drive app, the same shape as `../money/moneybird/` (read-only, no +npm dependencies): one ES module (`todoist-app/build.mjs`, minified, 25,926 +bytes for 0.1.0; `apps.mjs`'s `APP_FOLDERS` maps catalog id `todoist` to this +folder and publishes it as `apps/todoist//ui.js`) whose +`view({ root, store })` runs in the host's null-origin frame. It imports the +connected account's **active tasks** into its own table, nothing more; the +catalog entry `todoist` (`enabled: false`) installs it. + +**Flow.** "Connect Todoist" asks the host for a connection +(`store.proxy.connect`, the host's consent bar, platform `todoist`). With a +connection, every open of the view and every "Sync now" runs one pass +(`sync.ts`): `GET /api/v1/projects` and `GET /api/v1/tasks` through +`store.proxy.request`, paged by `cursor` at `limit=200`, at most 50 pages +(past that the read is reported partial); then `GET /api/v1/tasks/{id}` for +each previously imported task that a complete read no longer lists; then +`reconcileTodoistTasks` from `../todoist.ts`, whose table above says what +each row becomes. All reads happen before any write, so a failed read +leaves the table as it was. The view lists the table's tasks with their +status, presence, due day, priority, project and last-seen. + +**Rows** are of the shared class `issue-v1` (#177), like the GitHub issues +app's: on first open the app adds the class to its App's `renders`, its +extras to `row-extras`, and sets its table's `classtype` (`drive.ts`; +shown on another Issue table it says so and imports nothing). Shared fields +go through `ontology-kit`'s strict resolver: `name` (the task's `content`), +task/v1 `status` (`done` only when Todoist returned `checked: true`, else +`todo`), `body` (the task's `description`) and `due-date` (the due day). +The provider extras, created once under the app's own ontology: +`todoist-task-id` (the row's identity), `todoist-presence`, +`todoist-last-seen`, `todoist-priority`, `todoist-project` and +`todoist-source` (the task as Todoist last sent it, JSON text). A pass that +finds nothing changed writes no row: `last-seen` is kept off active rows +(an active task's last sighting is the App's `todoist-last-sync`, one write +per complete read), and only a task no longer in the active list carries +its own `todoist-last-seen`. + +**Local edits.** Todoist owns the imported columns: a local change to one +of them is overwritten at the next pass (#97's policy question; this plugin's +choice, the same as Moneybird's), and nothing is sent to Todoist. A row +made in the table by hand, with no Todoist task behind it, is left alone. + +**Tests.** `todoist-app/sync.test.ts` (the pass against an in-memory store +and the fixture: provisioning, import, a refresh that writes no row, and +every #99 case), `todoist-app/build.test.ts` (the bundle, its size limit and +a typecheck), `todoist-fixture.test.ts` (the fixture against `todoist.ts`), +and the lane's `e2e/todoist.spec.ts`: install from the catalog, connect, +import five tasks as `issue-v1` rows, a reload that leaves every row's +properties byte-for-byte the same, a task completed in Todoist that turns +up `completed` and done, and one made unreachable that turns up +`unavailable` and still open. Run them with: + +```sh +browser/node_modules/.bin/vitest run --config integrations/issue-tracker/vitest.config.ts todoist +node integrations/tooling/run-lane.mjs issue-tracker --tier e2e +``` + +**Not verified:** anything against a live Todoist account or the real +integration proxy (#46). ## Drive app (`app/`) diff --git a/integrations/issue-tracker/e2e/todoist.spec.ts b/integrations/issue-tracker/e2e/todoist.spec.ts new file mode 100644 index 000000000..5fd5d2116 --- /dev/null +++ b/integrations/issue-tracker/e2e/todoist.spec.ts @@ -0,0 +1,281 @@ +// @wc-ignore-file +/** + * The Todoist drive app (`../todoist-app/`, read-only active tasks) end to + * end: #99's host journey, against the mock integration proxy serving the + * SYNTHETIC todoist fixture (`../fixtures/todoist/`, hand-written from + * Todoist's API documentation, not a recording; #46 owns the recording). + * + * The app is installed from the catalog's Drive apps section, the way the + * GitHub issues spec does it; the lane's dev-server serves the committed + * `apps/todoist//ui.js` in place of GitHub Pages and the entry + * enabled although the published catalog keeps it `enabled: false`. + * + * Journey: + * 1. Install, connect through the host's consent bar and the mock proxy, + * import the five active tasks as rows of the shared class `issue-v1` + * (the app made itself a view of it: its table's class, its App's + * `renders`). + * 2. Reload: the refresh finds nothing changed and writes no row (every + * row's properties are byte-for-byte what they were). + * 3. Someone completes a task in Todoist (the fixture's `completeTask` + * driver): it leaves the active list, the app looks it up by id once, and + * the row becomes task/v1 done with presence `completed`. + * 4. Someone else makes a task unreachable (`removeTask`, 404 by id): its + * row is `unavailable`, stays open, keeps its values and says when it was + * last seen. Nothing is removed and nothing is sent to Todoist. + * + * The rows use the published GitHub Pages subject of `issue-v1`, which the + * pinned server and the browser fetch themselves, so `beforeAll` first checks + * Pages serves it with the committed bytes (ontology-kit/served.mjs); this + * needs network access to https://ontola.github.io. + * + * node integrations/tooling/run-lane.mjs issue-tracker --tier e2e + */ +import { test, expect, type Page } from '@playwright/test'; +import { before } from '../../../browser/e2e/tests/test-utils'; + +const APP_FRAME = 'iframe[title="App"]'; +/** The catalog's version of this app (integrations/catalog.json). */ +const VERSION = '0.1.0'; +const CLASSTYPE = 'https://atomicdata.dev/properties/classtype'; +const PARENT = 'https://atomicdata.dev/properties/parent'; +const IS_A = 'https://atomicdata.dev/properties/isA'; +const TASK = 'https://atomicdata.dev/task/v1'; + +test.describe('Todoist drive app', () => { + test.beforeAll(async () => { + const served = (await import( + '../../../ontology-kit/served.mjs' as string + )) as { + classTermPaths(name: string): string[]; + servedProblems(paths: string[]): Promise; + notServedMessage(problems: string[]): string; + }; + const problems = await served.servedProblems( + served.classTermPaths('issue-v1'), + ); + if (problems.length) throw new Error(served.notServedMessage(problems)); + }); + test.beforeEach(before); + + test('connects, imports active tasks as issue-v1, refreshes without writing, and settles tasks that disappear', async ({ + page, + }) => { + test.skip( + !process.env.ATOMIC_MOCK_INTEGRATION_PROXY, + 'Run with the documented mock integration-proxy server configuration', + ); + test.setTimeout(180_000); + const main = page.getByRole('main'); + const app = page.frameLocator(APP_FRAME); + const status = app.getByRole('status'); + const synced = status.filter({ hasText: 'Last synced' }); + const rows = app.locator('tr[data-task]'); + + // 1. Install from the catalog and connect. + await installFromCatalog(page); + await expect(app.getByRole('heading', { name: 'Todoist' })).toBeVisible({ + timeout: 30_000, + }); + await expect(status).toContainText('Not connected'); + await app.getByRole('button', { name: 'Connect Todoist' }).click(); + + const consent = page.getByRole('group', { name: 'Connect an account' }); + await expect(consent).toContainText('Todoist'); + await consent.getByRole('button', { name: 'Connect', exact: true }).click(); + await expect( + page.getByRole('heading', { name: 'Mock integration proxy' }), + ).toBeVisible(); + await page + .getByRole('button', { + name: 'Use LocalThought to sync Todoist with this destination', + exact: true, + }) + .click(); + await expect(page).not.toHaveURL(/connection_code=|integration_state=/); + + await expect(synced).toContainText( + '5 tasks (5 added, 0 updated, 0 unchanged); 5 active.', + { timeout: 60_000 }, + ); + await expect(rows).toHaveCount(5); + const plants = rows.filter({ hasText: 'Water the synthetic plants' }); + await expect(plants).toHaveAttribute('data-task', 'synthetic-task-1'); + await expect(plants).toContainText('Todo'); + await expect(plants).toContainText('active'); + await expect(plants).toContainText('2026-03-02'); + await expect(plants).toContainText('Urgent'); + await expect(plants).toContainText('Inbox'); + + // The shared class (#177): the rows, the table and the App. + const subjects = await rows.evaluateAll(trs => + trs.map(tr => (tr as HTMLElement).dataset.subject!), + ); + expect(subjects).toHaveLength(5); + const issueV1 = ( + (await import('../../../ontology-kit/terms.mjs' as string)) as { + classes: Record; + } + ).classes['issue-v1'].subject; + const appSubject = new URL(page.url()).searchParams.get('subject')!; + const shared = await page.evaluate( + async args => { + const store = window.store!; + await store.reloadResource(args.row); + const row = await store.getResource(args.row); + const table = await store.getResource(row.get(args.parent) as string); + await store.reloadResource(args.app); + const appResource = await store.getResource(args.app); + + return { + rowIsA: row.get(args.isA), + classtype: table.get(args.classtype), + table: table.subject, + renders: Object.values(appResource.getPropVals()).some( + v => Array.isArray(v) && v.includes(args.issueV1), + ), + }; + }, + { + row: subjects[0], + app: appSubject, + parent: PARENT, + isA: IS_A, + classtype: CLASSTYPE, + issueV1, + }, + ); + expect(shared).toMatchObject({ + rowIsA: [issueV1], + classtype: issueV1, + renders: true, + }); + const first = await propsOf(page, subjects); + for (const props of Object.values(first)) + expect(props[`${TASK}/status`]).toEqual([`${TASK}/todo`]); + + // 2. Reload: nothing changed in Todoist, so no row is written. + await page.reload(); + await expect(synced).toContainText( + '5 tasks (0 added, 0 updated, 5 unchanged); 5 active.', + { timeout: 60_000 }, + ); + expect(await propsOf(page, subjects)).toEqual(first); + + // 3. A task completed in Todoist: gone from the active list, confirmed + // by id, closed here. + await fixture('completeTask', ['synthetic-task-1']); + await app.getByRole('button', { name: 'Sync now' }).click(); + await expect(synced).toContainText( + '5 tasks (0 added, 1 updated, 4 unchanged); 4 active, 1 completed.', + { timeout: 60_000 }, + ); + await expect(rows).toHaveCount(5); + await expect(plants).toHaveAttribute('data-presence', 'completed'); + await expect(plants).toContainText('Done'); + const plantsSubject = (await plants.getAttribute('data-subject'))!; + const after = await propsOf(page, [plantsSubject]); + expect(after[plantsSubject][`${TASK}/status`]).toEqual([`${TASK}/done`]); + expect(Object.values(after[plantsSubject])).toContain('completed'); + + // 4. A task that can no longer be reached: unavailable, not closed, + // last values kept, with when it was last seen. + await fixture('removeTask', ['synthetic-task-3']); + await app.getByRole('button', { name: 'Sync now' }).click(); + await expect(synced).toContainText( + '3 active, 1 completed, 1 unavailable.', + { timeout: 60_000 }, + ); + const fence = rows.filter({ hasText: 'Paint the fictional fence' }); + await expect(fence).toHaveAttribute('data-presence', 'unavailable'); + await expect(fence).toContainText('Todo'); + await expect(fence).toContainText('Synthetic house'); + // Last seen: an ISO date and time, from the last complete read. + await expect(fence.locator('td').last()).toHaveText( + /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/, + ); + const fenceSubject = (await fence.getAttribute('data-subject'))!; + const gone = await propsOf(page, [fenceSubject]); + expect(gone[fenceSubject][`${TASK}/status`]).toEqual([`${TASK}/todo`]); + expect(Object.values(gone[fenceSubject])).toContain('unavailable'); + await expect(rows).toHaveCount(5); + + // Nothing reached Todoist: the fixture's tasks changed only through its + // own drivers (checked and unreachable are what the drivers set). + const snapshot = (await fixture('snapshot', [])) as { + tasks: { id: string; checked: boolean }[]; + unreachable: string[]; + }; + expect(snapshot.tasks.filter(t => t.checked).map(t => t.id)).toEqual([ + 'synthetic-task-1', + ]); + expect(snapshot.unreachable).toEqual(['synthetic-task-3']); + + // The typed table outside the app shows the tasks. + await page.goto( + `${new URL(page.url()).origin}/app/show?subject=${encodeURIComponent(shared.table)}`, + ); + for (const name of [ + 'Water the synthetic plants', + 'Call the invented plumber', + 'Return the made-up library books', + ]) + await expect(main.getByText(name, { exact: true }).first()).toBeVisible({ + timeout: 30_000, + }); + }); +}); + +/** Every property of each row, read fresh from the server. */ +async function propsOf( + page: Page, + subjects: string[], +): Promise>> { + return page.evaluate(async list => { + const store = window.store!; + const out: Record> = {}; + + for (const subject of list) { + await store.reloadResource(subject); + const resource = await store.getResource(subject); + out[subject] = { ...resource.getPropVals() }; + } + + return out; + }, subjects); +} + +/** One todoist fixture driver on the mock proxy: someone working in Todoist. */ +async function fixture(name: string, args: unknown[]): Promise { + const response = await fetch( + `${process.env.INTEGRATION_PROXY_URL}/fixture/todoist/${name}`, + { method: 'POST', body: JSON.stringify(args) }, + ); + if (!response.ok) throw new Error(`${name}: HTTP ${response.status}`); + + return response.json(); +} + +/** + * Installs the app the way a user does: Integrations page, experimental + * plugins shown, Drive apps, Install. The host downloads the catalog's + * `app-module` and refuses it unless its bytes match + * `app-module-integrity`, then opens the new app. + */ +async function installFromCatalog(page: Page) { + await page.goto(new URL('/app/integrations', page.url()).href); + const experimental = page.getByRole('checkbox', { + name: 'Show experimental plugins', + }); + await experimental.check(); + // Disabled while the setting is still saving to the private drive. + await expect(experimental).toBeEnabled({ timeout: 30_000 }); + const entry = page + .getByRole('region', { name: 'Drive apps' }) + .locator('[data-catalog-app="todoist"]'); + await expect(entry).toContainText(`Version ${VERSION}`); + await entry.getByRole('button', { name: 'Install Todoist' }).click(); + await expect(page.getByRole('main').locator(APP_FRAME)).toBeVisible({ + timeout: 45_000, + }); +} diff --git a/integrations/issue-tracker/fixtures/todoist/record.mjs b/integrations/issue-tracker/fixtures/todoist/record.mjs index 942949fbb..ea18ea233 100644 --- a/integrations/issue-tracker/fixtures/todoist/record.mjs +++ b/integrations/issue-tracker/fixtures/todoist/record.mjs @@ -38,18 +38,14 @@ * For todoist.ts coverage, include a task with `due.date`, one with * `due.datetime`, one with no due date, and several priorities. * - * After recording, register the fixture in the shared registry, - * integrations/localthought/fixtures/index.mjs, which imports each plugin's - * fixture by relative path, sorted by that path: - * import todoist from '../../issue-tracker/fixtures/todoist/scenario.mjs'; - * (right after the github-issues import), and add `todoist,` to `fixtures`. - * Whether atomic-server's dagger e2e resolves these cross-folder imports is - * tracked in ontola/atomic-server#1639. - * integrations/localthought/mock-proxy.test.mjs uses todoist as its example - * of a platform with no fixture (`platforms: 'pets,todoist,pets'`) and lists - * every served platform, so change it in the same commit. Then run - * integrations/issue-tracker/todoist-fixture.test.ts (its header has the - * command) and `node --test integrations/localthought/mock-proxy.test.mjs`. + * The fixture (scenario.mjs) is already registered in + * integrations/localthought/fixtures/index.mjs. Until api/ exists it serves + * the SYNTHETIC rows of synthetic.mjs; once this script has written api/, it + * replays the recording instead, and synthetic.mjs can be deleted. After + * recording, run integrations/issue-tracker/todoist-fixture.test.ts (its + * header has the command): the recorded-only tests stop skipping, and the + * app's unit tests and the lane's e2e (todoist.spec.ts) then run against the + * recorded rows, so their expected names and counts need updating to match. */ import { spawnSync } from 'node:child_process'; import { diff --git a/integrations/issue-tracker/fixtures/todoist/scenario.mjs b/integrations/issue-tracker/fixtures/todoist/scenario.mjs index 861155034..bb6b9cad8 100644 --- a/integrations/issue-tracker/fixtures/todoist/scenario.mjs +++ b/integrations/issue-tracker/fixtures/todoist/scenario.mjs @@ -1,30 +1,55 @@ /** - * Todoist fixture: replays the recorded, redacted API v1 pages in api/ and - * the recorded catalog document in document.yaml. Both are written by - * record.mjs; nothing here is hand-written data. + * Todoist mock-proxy fixture, registered as `todoist` in + * integrations/localthought/fixtures/index.mjs. Its data comes from one of + * two sources, in this order: + * + * api/ the recorded, redacted API v1 pages record.mjs writes + * against a real account (#46). Not present yet. + * synthetic.mjs SYNTHETIC rows hand-written from Todoist's API + * documentation (read its header). Used until api/ exists. + * + * `recorded()` says which. document.yaml, the catalog document, is recorded + * from the real proxy either way (record.mjs --document-only). * * Served, read-only like the real proxy's `data:read` catalog: * GET /proxy/todoist/api/v1/projects[?cursor=page-] - * GET /proxy/todoist/api/v1/tasks[?cursor=page-] + * GET /proxy/todoist/api/v1/tasks[?cursor=page-][&project_id=] + * — the ACTIVE tasks, as Todoist's /tasks lists only those: a task + * the `completeTask`, `deleteTask` or `removeTask` driver touched + * is left out. * GET /proxy/todoist/api/v1/projects/, /tasks/ - * — the matching row from the recorded pages, else 404. + * — the row as it now stands: `checked: true` after completeTask, + * `is_deleted: true` after deleteTask, 404 after removeTask or for + * an unknown id. * Any other method is 403 (the real catalog allows GET only); any other path - * 404. `limit` is ignored: pages are replayed at the recorded size. The - * `project_id` filter on /tasks is applied to the recorded rows and returned - * as one page — derived, not separately recorded. + * 404. `limit` is ignored: pages hold PAGE_SIZE rows (the recorded page + * size, or 3 for the synthetic rows, so five tasks span two pages). + * + * Test drivers (POST /fixture/todoist/ on the mock proxy, or the + * instance's methods in-process) stand in for someone working in Todoist and + * for Todoist failing. They are the fixture's own and claim nothing about + * Todoist beyond what synthetic.mjs's header says: + * completeTask(id) checks the task off: gone from /tasks, by id checked. + * reopenTask(id) back in /tasks (also undoes deleteTask/removeTask). + * deleteTask(id) gone from /tasks; by id with is_deleted: true. + * removeTask(id) gone from /tasks; by id 404 (lost access, or deleted + * for good: Todoist would not say which). + * failNext(count, status = 503, only = 'any' | 'list' | 'lookup') + * the next `count` matching requests answer `status`. + * snapshot() every task row, active or not. * - * Lives in the issue-tracker plugin folder, whose lane names todoist. Not - * registered in integrations/localthought/fixtures/index.mjs until api/ has - * been recorded; see record.mjs for the command and the registration step. + * Lives in the issue-tracker plugin folder, whose lane names todoist. */ import { existsSync, readFileSync } from 'node:fs'; +import * as synthetic from './synthetic.mjs'; const api = new URL('./api/', import.meta.url); const COLLECTIONS = ['projects', 'tasks']; +const SYNTHETIC_PAGE_SIZE = 3; export const recorded = () => existsSync(new URL('meta.json', api)); -function load(collection) { +function loadPages(collection) { const pages = []; for (let n = 1; ; n++) { @@ -36,16 +61,89 @@ function load(collection) { return pages; } -export function todoistFixture() { +/** The rows to start from and the page size, from api/ or synthetic.mjs. */ +export function source() { if (!recorded()) - throw new Error( - 'todoist fixture has no recording; run fixtures/todoist/record.mjs', - ); - const pages = Object.fromEntries(COLLECTIONS.map(c => [c, load(c)])); + return { + synthetic: true, + pageSize: SYNTHETIC_PAGE_SIZE, + projects: structuredClone(synthetic.projects), + tasks: structuredClone(synthetic.tasks), + }; + const pages = Object.fromEntries(COLLECTIONS.map(c => [c, loadPages(c)])); const rows = c => pages[c].flatMap(page => page.body.results); return { - pages, + synthetic: false, + pageSize: pages.tasks[0]?.body.results.length || SYNTHETIC_PAGE_SIZE, + projects: rows('projects'), + tasks: rows('tasks'), + }; +} + +export function todoistFixture() { + const { synthetic: isSynthetic, pageSize, projects, tasks } = source(); + const byId = new Map(tasks.map(t => [t.id, t])); + /** Ids the `removeTask` driver made unreachable (404 by id). */ + const gone = new Set(); + const failures = []; + + const active = () => + tasks.filter(t => !t.checked && !t.is_deleted && !gone.has(t.id)); + + const paged = (rows, cursor) => { + const n = cursor ? Number(/^page-(\d+)$/.exec(cursor)?.[1]) : 1; + if (!Number.isInteger(n) || n < 1) + return { status: 400, body: { error: 'Invalid cursor' } }; + const start = (n - 1) * pageSize; + if (start > 0 && start >= rows.length) + return { status: 400, body: { error: 'Invalid cursor' } }; + const results = structuredClone(rows.slice(start, start + pageSize)); + + return { + status: 200, + body: { + results, + next_cursor: start + pageSize < rows.length ? `page-${n + 1}` : null, + }, + }; + }; + + const must = id => { + const row = byId.get(id); + if (!row) throw new Error(`no task ${id}`); + + return row; + }; + + const pages = () => { + const out = {}; + + for (const [collection, rows] of [ + ['projects', projects], + ['tasks', active()], + ]) { + out[collection] = []; + let cursor; + + do { + const page = paged(rows, cursor); + out[collection].push(page); + cursor = page.body.next_cursor; + } while (cursor); + } + + return out; + }; + + return { + synthetic: isSynthetic, + pageSize, + /** The collections as the pages they are served in now (tests). */ + get pages() { + return pages(); + }, + request(method, url) { const match = url.pathname.match( /^\/proxy\/todoist\/api\/v1\/(projects|tasks)(?:\/([^/]+))?$/, @@ -53,34 +151,84 @@ export function todoistFixture() { if (!match) return { status: 404, body: {} }; if (method !== 'GET') return { status: 403, body: {} }; const [, collection, id] = match; + const kind = id ? 'lookup' : 'list'; + const at = failures.findIndex(f => f.only === 'any' || f.only === kind); + + if (at !== -1) { + const failure = failures[at]; + if (--failure.count <= 0) failures.splice(at, 1); + + return { + status: failure.status, + body: { error: `Synthetic failure (${failure.status})` }, + }; + } if (id) { - const row = rows(collection).find(r => r.id === id); + const row = + collection === 'tasks' + ? gone.has(id) + ? undefined + : byId.get(id) + : projects.find(p => p.id === id); return row ? { status: 200, body: structuredClone(row) } : { status: 404, body: {} }; } + const rows = collection === 'projects' ? projects : active(); const projectId = url.searchParams.get('project_id'); - if (collection === 'tasks' && projectId) - return { - status: 200, - body: { - results: rows('tasks').filter(t => t.project_id === projectId), - next_cursor: null, - }, - }; - const cursor = url.searchParams.get('cursor'); - const n = cursor ? Number(/^page-(\d+)$/.exec(cursor)?.[1]) : 1; - const page = pages[collection][n - 1]; - if (!page) return { status: 400, body: { error: 'Invalid cursor' } }; + return paged( + collection === 'tasks' && projectId + ? rows.filter(t => t.project_id === projectId) + : rows, + url.searchParams.get('cursor'), + ); + }, + // Drivers. + completeTask(id) { + const row = must(id); + row.checked = true; + row.completed_at = '2026-03-01T12:00:00.000000Z'; + row.updated_at = row.completed_at; + + return structuredClone(row); + }, + reopenTask(id) { + const row = must(id); + row.checked = false; + row.completed_at = null; + row.is_deleted = false; + gone.delete(id); + + return structuredClone(row); + }, + deleteTask(id) { + const row = must(id); + row.is_deleted = true; + + return structuredClone(row); + }, + removeTask(id) { + must(id); + gone.add(id); + + return { id, status: 404 }; + }, + failNext(count = 1, status = 503, only = 'any') { + if (!['any', 'list', 'lookup'].includes(only)) + throw new Error(`failNext: only must be any, list or lookup`); + failures.push({ count, status, only }); + + return { failures: failures.map(f => ({ ...f })) }; + }, + snapshot() { return { - status: page.status, - body: structuredClone(page.body), - headers: page.headers, + tasks: structuredClone(tasks), + unreachable: [...gone], }; }, }; @@ -91,4 +239,14 @@ export default { // Served verbatim with a YAML content type, as the real proxy does. documentFile: new URL('./document.yaml', import.meta.url), create: todoistFixture, + // For the drive app's e2e: someone completing, deleting or hiding a task + // in Todoist, and Todoist failing. + drivers: [ + 'completeTask', + 'reopenTask', + 'deleteTask', + 'removeTask', + 'failNext', + 'snapshot', + ], }; diff --git a/integrations/issue-tracker/fixtures/todoist/synthetic.mjs b/integrations/issue-tracker/fixtures/todoist/synthetic.mjs new file mode 100644 index 000000000..c4e140b0e --- /dev/null +++ b/integrations/issue-tracker/fixtures/todoist/synthetic.mjs @@ -0,0 +1,136 @@ +/** + * SYNTHETIC Todoist data. NOT RECORDED. + * + * Nobody working on this repository had a Todoist test account when the + * Todoist drive app (todoist-app/) needed a mock-proxy fixture, so these + * bodies are hand-written from Todoist's public API v1 documentation + * (https://developer.todoist.com/api/v1/, "Get active tasks", "Get a task", + * "Get all projects"): the field names, their types and the paged envelope + * `{ results, next_cursor }`. Every id, name, task text and timestamp is + * invented; the ids say so (`synthetic-…`). None belongs to a real account. + * Recording the real thing is #46's job (record.mjs); once api/ exists, + * scenario.mjs replays that instead of this file. + * + * What this cannot tell you: whether real responses carry fields, nulls or + * values this file does not, and what Todoist answers for `GET /tasks/{id}` + * on a completed task. todoist.ts reads `checked: true` from such an answer + * (its README explains the fallback when the answer is 404 instead), and + * scenario.mjs's `completeTask` driver answers that way. That is a modelling + * choice of this fixture, declared, not verified against Todoist. + * + * The five tasks cover what todoist.ts reads: a due date, a due date with a + * time, no due date, every priority from 1 (normal) to 4 (urgent), an empty + * and a non-empty description, and two projects. + */ + +export const SYNTHETIC = true; + +const INBOX = 'synthetic-project-1'; +const HOUSE = 'synthetic-project-2'; +const USER = 'synthetic-user-1'; + +/** A project as "Get all projects" documents it, with synthetic values. */ +function project(id, name, over = {}) { + return { + id, + name, + color: 'charcoal', + parent_id: null, + child_order: 1, + view_style: 'list', + is_favorite: false, + is_archived: false, + is_deleted: false, + is_frozen: false, + can_assign_tasks: false, + created_at: '2026-01-05T09:00:00.000000Z', + updated_at: '2026-01-05T09:00:00.000000Z', + inbox_project: false, + is_collapsed: false, + is_shared: false, + description: '', + default_order: 0, + creator_uid: USER, + url: `https://app.todoist.com/app/project/${id}`, + ...over, + }; +} + +export const projects = [ + project(INBOX, 'Inbox', { inbox_project: true, color: 'grey' }), + project(HOUSE, 'Synthetic house', { child_order: 2, color: 'teal' }), +]; + +/** A task as "Get active tasks" documents it, with synthetic values. */ +function task(n, projectId, content, over = {}) { + const id = `synthetic-task-${n}`; + + return { + id, + user_id: USER, + project_id: projectId, + section_id: null, + parent_id: null, + added_by_uid: USER, + assigned_by_uid: null, + responsible_uid: null, + labels: [], + deadline: null, + duration: null, + checked: false, + is_deleted: false, + added_at: `2026-02-0${n}T08:00:00.000000Z`, + completed_at: null, + updated_at: `2026-02-0${n}T08:30:00.000000Z`, + due: null, + priority: 1, + child_order: n, + content, + description: '', + note_count: 0, + day_order: -1, + is_collapsed: false, + url: `https://app.todoist.com/app/task/${id}`, + ...over, + }; +} + +export const tasks = [ + task(1, INBOX, 'Water the synthetic plants', { + due: { + date: '2026-03-02', + string: 'Mar 2', + lang: 'en', + is_recurring: false, + timezone: null, + }, + priority: 4, + }), + task(2, INBOX, 'Call the invented plumber', { + due: { + date: '2026-03-03', + datetime: '2026-03-03T09:30:00Z', + string: 'Mar 3 10:30', + lang: 'en', + is_recurring: false, + timezone: 'Europe/Amsterdam', + }, + priority: 3, + description: 'Ask about the imaginary leak under the sink.', + }), + task(3, HOUSE, 'Paint the fictional fence', { + priority: 2, + labels: ['synthetic-label-outdoors'], + }), + task(4, HOUSE, 'Sort the pretend attic', { + due: { + date: '2026-03-20', + string: 'every month', + lang: 'en', + is_recurring: true, + timezone: null, + }, + priority: 1, + }), + task(5, HOUSE, 'Return the made-up library books', { priority: 1 }), +]; diff --git a/integrations/issue-tracker/todoist-app/atomic-lib-shim.ts b/integrations/issue-tracker/todoist-app/atomic-lib-shim.ts new file mode 100644 index 000000000..1e8937874 --- /dev/null +++ b/integrations/issue-tracker/todoist-app/atomic-lib-shim.ts @@ -0,0 +1,23 @@ +// @wc-ignore-file +/** + * Build-time stand-in for `../../browser/lib/src/index.js` in the drive-app + * bundle only (build.mjs resolves that path here). `../todoist.ts` imports + * `Datatype` from it for the five projected properties' datatypes, and + * nothing else; bundling the whole library into a module stored as a string + * on a resource is not worth that. Typecheck and tests use the real library; + * build.test.ts pins every value here to it. + */ +export const Datatype = { + ATOMIC_URL: 'https://atomicdata.dev/datatypes/atomicURL', + BOOLEAN: 'https://atomicdata.dev/datatypes/boolean', + DATE: 'https://atomicdata.dev/datatypes/date', + FLOAT: 'https://atomicdata.dev/datatypes/float', + INTEGER: 'https://atomicdata.dev/datatypes/integer', + JSON: 'https://atomicdata.dev/datatypes/json', + MARKDOWN: 'https://atomicdata.dev/datatypes/markdown', + RESOURCEARRAY: 'https://atomicdata.dev/datatypes/resourceArray', + SLUG: 'https://atomicdata.dev/datatypes/slug', + STRING: 'https://atomicdata.dev/datatypes/string', + TIMESTAMP: 'https://atomicdata.dev/datatypes/timestamp', + UNKNOWN: 'unknown-datatype', +} as const; diff --git a/integrations/issue-tracker/todoist-app/build.mjs b/integrations/issue-tracker/todoist-app/build.mjs new file mode 100644 index 000000000..690344633 --- /dev/null +++ b/integrations/issue-tracker/todoist-app/build.mjs @@ -0,0 +1,78 @@ +// @wc-ignore-file +/** + * Builds the Todoist drive app to one ES module: the string an install flow + * stores as the App's `plugin-source`. Prints its size and hash; writes a + * file only when asked to. + * + * node integrations/issue-tracker/todoist-app/build.mjs [--outfile path] + * + * Needs an atomic-server checkout's `browser/` beside `integrations/` (see + * AGENTS.md), for esbuild. No npm dependencies of its own: it bundles + * ../todoist.ts, ontology-kit's terms and resolver, and the small + * `Datatype` shim that stands in for the atomic library ../todoist.ts + * imports (atomic-lib-shim.ts). No code splitting and no CSS file: "a plugin + * in the drive is one module". + */ +import { createHash } from 'node:crypto'; +import { createRequire } from 'node:module'; +import { fileURLToPath } from 'node:url'; +import { mkdirSync, writeFileSync } from 'node:fs'; +import { dirname } from 'node:path'; + +const path = relative => fileURLToPath(new URL(relative, import.meta.url)); + +/** `../../browser/lib/src/index.js` (as ../todoist.ts and read.ts import it) -> the shim. */ +const atomicLibShim = { + name: 'atomic-lib-shim', + setup(bundle) { + bundle.onResolve({ filter: /browser\/lib\/src\/index\.js$/ }, () => ({ + path: path('atomic-lib-shim.ts'), + })); + }, +}; + +/** Bundles in memory; writes only when `outfile` is given. */ +export async function build({ outfile } = {}) { + const require = createRequire(path('../../../browser/package.json')); + const esbuild = require('esbuild'); + const result = await esbuild.build({ + entryPoints: [path('main.ts')], + // esbuild's `// path` comments and any path it embeds are relative to + // this, so pin it to the repository root: the bytes (and the catalog's + // integrity hash for them) must not depend on the directory the build + // was started from. + absWorkingDir: path('../../..'), + bundle: true, + format: 'esm', + platform: 'browser', + target: 'es2022', + splitting: false, + minify: true, + legalComments: 'none', + write: false, + outfile: outfile ?? path('dist/ui.js'), + plugins: [atomicLibShim], + logLevel: 'silent', + }); + const text = result.outputFiles[0].text; + + if (outfile) { + mkdirSync(dirname(outfile), { recursive: true }); + writeFileSync(outfile, text); + } + + return { + text, + bytes: Buffer.byteLength(text), + sha256: createHash('sha256').update(text).digest('hex'), + }; +} + +if (process.argv[1] === fileURLToPath(import.meta.url)) { + const at = process.argv.indexOf('--outfile'); + const outfile = at > 0 ? process.argv[at + 1] : undefined; + const out = await build({ outfile }); + console.info( + `${outfile ?? 'todoist app'}: ${out.bytes} bytes, sha256 ${out.sha256}`, + ); +} diff --git a/integrations/issue-tracker/todoist-app/build.test.ts b/integrations/issue-tracker/todoist-app/build.test.ts new file mode 100644 index 000000000..a7cf52109 --- /dev/null +++ b/integrations/issue-tracker/todoist-app/build.test.ts @@ -0,0 +1,63 @@ +// @wc-ignore-file +import { spawnSync } from 'node:child_process'; +import { fileURLToPath } from 'node:url'; +import { Datatype } from '../../../browser/lib/src/index'; +import { describe, expect, it } from 'vitest'; +// @ts-expect-error build.mjs is plain JS with no declaration file. +import { build } from './build.mjs'; +import * as shim from './atomic-lib-shim.js'; +import { ISSUE_V1 } from './drive.js'; + +describe('Todoist drive-app bundle', async () => { + const { text, bytes } = (await build()) as { text: string; bytes: number }; + + it('is one self-contained ES module exporting view()', async () => { + expect(text).not.toMatch(/^\s*import\s/m); + expect(text).not.toMatch(/\bimport\(/); + expect(text).not.toMatch(/node:|require\(/); + const mod = await import( + `data:text/javascript;base64,${Buffer.from(text).toString('base64')}` + ); + expect(Object.keys(mod)).toEqual(['view']); + expect(typeof mod.view).toBe('function'); + // Measured 25,926 bytes minified on 2026-10-02 for 0.1.0, at the + // a12b74a6783b pin: ../todoist.ts, ontology-kit's terms and resolver, + // the issue-v1 provisioning and the plain-DOM view. The limit is that + // plus about 10%, rounded up. + expect(bytes).toBeLessThan(28_600); + }); + + it('carries no credential handling, network access or fixture data', () => { + expect(text).not.toMatch(/localStorage|sessionStorage|indexedDB/); + expect(text).not.toMatch(/authorization|bearer|connection-code/i); + expect(text).not.toMatch(/\bfetch\(|XMLHttpRequest/); + expect(text).not.toMatch(/synthetic-task|Synthetic house/); + }); + + it('bundles the shim, not the atomic library, and the published issue-v1 subject', () => { + expect(text).not.toMatch(/Conflicting identity mapping|class Store\b/); + expect(text).toContain(ISSUE_V1); + }); + + it("uses the real library's Datatype values through the shim", () => { + for (const [key, value] of Object.entries(shim.Datatype)) + expect(Datatype[key as keyof typeof Datatype]).toBe(value); + }); +}); + +describe('Todoist drive-app types', () => { + // vitest strips types without checking them; the lane has no typecheck + // tier for todoist-app/, so its tsconfig is checked here. + it('typechecks', () => { + const tsc = fileURLToPath( + new URL('../../../browser/node_modules/.bin/tsc', import.meta.url), + ); + const result = spawnSync( + tsc, + ['-p', fileURLToPath(new URL('tsconfig.json', import.meta.url))], + { encoding: 'utf8' }, + ); + expect(result.stdout + result.stderr).toBe(''); + expect(result.status).toBe(0); + }, 120_000); +}); diff --git a/integrations/issue-tracker/todoist-app/controller.ts b/integrations/issue-tracker/todoist-app/controller.ts new file mode 100644 index 000000000..c626569e1 --- /dev/null +++ b/integrations/issue-tracker/todoist-app/controller.ts @@ -0,0 +1,196 @@ +// @wc-ignore-file +/** + * The view's state machine: find this app's Todoist connection, provision the + * drive (once), import on open and on "Sync now". Nothing runs while the view + * is closed, and nothing is written to Todoist. + */ +import { type Drive, OtherTable, provision } from './drive.js'; +import type { PluginStore } from './store.js'; +import { + listTasks, + PLATFORM, + relayGet, + syncTasks, + type SyncOptions, + type SyncSummary, + type TaskRow, +} from './sync.js'; + +type Connection = { connectionId: string; platform: string }; + +export type ViewState = + | { kind: 'loading' } + /** The host has no proxy client for apps (atomic-server#1657 not in this build). */ + | { kind: 'no-relay' } + /** Added as a view of another Issue table: the app shows nothing of its own. */ + | { kind: 'other-table' } + | { kind: 'disconnected'; tasks: TaskRow[] } + | { kind: 'connecting'; tasks: TaskRow[] } + | { kind: 'syncing'; connection: Connection; tasks: TaskRow[] } + | { + kind: 'synced'; + connection: Connection; + at: Date; + summary: SyncSummary; + tasks: TaskRow[]; + } + | { + kind: 'error'; + message: string; + connection?: Connection; + tasks: TaskRow[]; + }; + +const PRESENCE_WORDS: Record = { + completed: 'completed', + deleted: 'deleted', + unavailable: 'unavailable', + unconfirmed: 'unconfirmed', +}; + +/** "5 tasks (5 added, 0 updated, 0 unchanged); 4 active, 1 completed". */ +export function describeSummary(s: SyncSummary): string { + const counts = `${s.total} task${s.total === 1 ? '' : 's'} (${s.added} added, ${s.updated} updated, ${s.unchanged} unchanged)`; + const presence = [`${s.presence.active} active`]; + + for (const [key, word] of Object.entries(PRESENCE_WORDS)) { + const n = s.presence[key as keyof SyncSummary['presence']]; + if (n) presence.push(`${n} ${word}`); + } + + const partial = s.complete + ? '' + : ' The read was partial, so no missing task was checked.'; + + return `${counts}; ${presence.join(', ')}.${partial}`; +} + +export function describe(state: ViewState): string { + switch (state.kind) { + case 'loading': + return 'Loading…'; + case 'no-relay': + return 'This host cannot reach the integration proxy for apps yet.'; + case 'other-table': + return 'This is another Issue table. The Todoist app imports only into its own table.'; + case 'disconnected': + return 'Not connected. Connect Todoist to import your active tasks (read-only).'; + case 'connecting': + return 'Waiting for you to confirm the connection…'; + case 'syncing': + return 'Importing tasks…'; + case 'synced': + return `Last synced ${state.at.toLocaleTimeString()}: ${describeSummary(state.summary)}`; + case 'error': + return `Refresh failed: ${state.message} Tasks imported earlier are kept.`; + } +} + +const message = (error: unknown) => + error instanceof Error ? error.message : String(error); + +export function createController( + store: PluginStore, + render: (state: ViewState) => void, + options: SyncOptions = {}, +) { + let state: ViewState = { kind: 'loading' }; + let drive: Drive | undefined; + + const set = (next: ViewState) => { + state = next; + render(state); + }; + + const tasks = () => ('tasks' in state ? state.tasks : []); + + /** Provisions once; `OtherTable` is a state, anything else an error. */ + const ready = async (): Promise => { + if (drive) return drive; + + try { + drive = await provision(store); + } catch (error) { + if (error instanceof OtherTable) set({ kind: 'other-table' }); + else set({ kind: 'error', message: message(error), tasks: tasks() }); + + return undefined; + } + + return drive; + }; + + const listed = async (): Promise => + drive ? listTasks(store, drive).catch(() => tasks()) : tasks(); + + const controller = { + state: () => state, + + /** + * Finds this app's connection, then starts one sync. Resolves once that + * is known, not when the sync ends. + */ + async load(): Promise<{ syncing?: Promise }> { + const proxy = store.proxy; + if (!proxy) return (set({ kind: 'no-relay' }), {}); + if (!(await ready())) return {}; + const rows = await listed(); + const [connection] = await proxy.connections({ platform: PLATFORM }); + if (!connection) return (set({ kind: 'disconnected', tasks: rows }), {}); + + return { syncing: controller.sync(connection) }; + }, + + async connect(): Promise { + const proxy = store.proxy; + if (!proxy) return set({ kind: 'no-relay' }); + set({ kind: 'connecting', tasks: tasks() }); + + try { + // Connecting a new account sends the page away and this view reloads; + // picking an existing connection resolves here with no reload. + const result = await proxy.connect({ platform: PLATFORM }); + if (result.status === 'connected') await controller.sync(result); + else set({ kind: 'disconnected', tasks: tasks() }); + } catch (error) { + set({ kind: 'error', message: message(error), tasks: tasks() }); + } + }, + + async sync( + connection = 'connection' in state ? state.connection : undefined, + ): Promise { + const proxy = store.proxy; + if (!proxy) return set({ kind: 'no-relay' }); + if (!connection || state.kind === 'syncing') return; + const d = await ready(); + if (!d) return; + set({ kind: 'syncing', connection, tasks: tasks() }); + + try { + const summary = await syncTasks( + store, + relayGet(proxy, connection), + d, + options, + ); + set({ + kind: 'synced', + connection, + at: new Date(), + summary, + tasks: await listed(), + }); + } catch (error) { + set({ + kind: 'error', + connection, + message: message(error), + tasks: await listed(), + }); + } + }, + }; + + return controller; +} diff --git a/integrations/issue-tracker/todoist-app/drive.ts b/integrations/issue-tracker/todoist-app/drive.ts new file mode 100644 index 000000000..e71af8fcd --- /dev/null +++ b/integrations/issue-tracker/todoist-app/drive.ts @@ -0,0 +1,329 @@ +// @wc-ignore-file +/** + * The app's own data in the user's drive, laid out like the GitHub issues + * app's (../app/tracker.ts) so that any view of the shared class reads it: + * + * - Rows are of the shared class `issue-v1` (ontola/atomic-plugins#177), + * published on GitHub Pages. Shared fields, by subject through + * `ontology-kit`'s strict resolver in sync.ts: Atomic's `name` as the + * task text, task/v1 `status` (the todo or done tag), `body` (the task's + * description) and `due-date` (the due day). + * - Provider extras are the app's own properties under its own ontology + * (the App's default ontology, as `createApp` sets it), created once and + * found again by shortname: the Todoist task id (the row's identity), + * presence and last-seen (#99), priority, project, and the task as + * Todoist last sent it (JSON text). They are declared as the App's + * `row-extras` (atomic-server #1849). + * - The time of the last complete read is one string property on the App + * resource, not on each row, so a refresh that finds nothing changed + * writes no row (see sync.ts). + * + * On first open (`provision`) the app makes itself a view of `issue-v1`: it + * adds the class to its App's `renders`, its extras to `row-extras`, and + * sets its own table's `classtype` to the class (#177 spike S2; a catalog + * Install cannot do that yet, #177 H2). Every lookup goes through a resource + * the host reads back, so running this twice creates nothing twice. + */ +import { classes as shared } from '../../../ontology-kit/terms.mjs'; +import type { JSONValue, PluginResource, PluginStore } from './store.js'; + +const A = 'https://atomicdata.dev'; + +export const PARENT = `${A}/properties/parent`; +export const IS_A = `${A}/properties/isA`; +export const NAME = `${A}/properties/name`; +export const SHORTNAME = `${A}/properties/shortname`; +export const DESCRIPTION = `${A}/properties/description`; +export const DATATYPE = `${A}/properties/datatype`; +export const RECOMMENDS = `${A}/properties/recommends`; +export const PROPERTIES = `${A}/properties/properties`; +export const CLASSTYPE = `${A}/properties/classtype`; +export const PROPERTY_CLASS = `${A}/classes/Property`; +/** The drive's default ontology on an App (`createApp` sets it). */ +export const DEFAULT_ONTOLOGY = `${A}/ontology/server/property/default-ontology`; + +/** The shared class this app's rows are (#177 §2.3). */ +export const ISSUE_V1: string = shared['issue-v1'].subject; +const TASK = `${A}/task/v1`; + +/** task/v1 terms every AtomicServer embeds; `issue-v1` recommends them. */ +export const TASK_STATUS = `${TASK}/status`; +export const TASK_BODY = `${TASK}/body`; +export const TASK_DUE_DATE = `${TASK}/due-date`; +/** The two task/v1 tags a read-only import can mean: open, or checked off. */ +export const TAG_TODO = `${TASK}/todo`; +export const TAG_DONE = `${TASK}/done`; + +export const TABLE_NAME = 'Todoist tasks'; + +const datatypes = { + string: `${A}/datatypes/string`, +}; + +/** The app's own properties, by role. */ +export type OwnProperty = + | 'taskId' + | 'presence' + | 'lastSeen' + | 'priority' + | 'project' + | 'source' + | 'lastSync'; + +interface PropertySpec { + key: OwnProperty; + shortname: string; + name: string; + datatype: string; + description: string; +} + +export const PROPERTY_SPECS: PropertySpec[] = [ + { + key: 'taskId', + shortname: 'todoist-task-id', + name: 'Todoist task', + datatype: datatypes.string, + description: + 'The id of the Todoist task this row was imported from. The row’s identity across imports.', + }, + { + key: 'presence', + shortname: 'todoist-presence', + name: 'Todoist presence', + datatype: datatypes.string, + description: + 'Where the task stands in Todoist: active, completed, deleted, unavailable (gone, reason unknown) or unconfirmed (last known values; see Todoist last seen).', + }, + { + key: 'lastSeen', + shortname: 'todoist-last-seen', + name: 'Todoist last seen', + datatype: datatypes.string, + description: + 'When Todoist last returned this task, as an ISO 8601 date and time. Set only on a task that is no longer in the active list; an active task was seen at the app’s last sync.', + }, + { + key: 'priority', + shortname: 'todoist-priority', + name: 'Todoist priority', + datatype: datatypes.string, + description: 'Todoist priority: Normal, Medium, High or Urgent.', + }, + { + key: 'project', + shortname: 'todoist-project', + name: 'Todoist project', + datatype: datatypes.string, + description: 'The name of the Todoist project the task is in.', + }, + { + key: 'source', + shortname: 'todoist-source', + name: 'Todoist source', + datatype: datatypes.string, + description: + 'JSON text written by the Todoist app: the task as Todoist last sent it, with the app’s presence fields. Edit it and the next import can no longer tell what Todoist said.', + }, + { + key: 'lastSync', + shortname: 'todoist-last-sync', + name: 'Todoist last sync', + datatype: datatypes.string, + description: + 'When the Todoist app last read the complete active-task list, as an ISO 8601 date and time. On the App resource.', + }, +]; + +/** The provider extras kept on rows, declared as the App's `row-extras`. */ +export const ROW_EXTRAS: OwnProperty[] = [ + 'taskId', + 'presence', + 'lastSeen', + 'priority', + 'project', + 'source', +]; + +export const asList = (value: JSONValue): string[] => + Array.isArray(value) + ? value.filter((v): v is string => typeof v === 'string') + : []; + +async function ensureProperties( + store: PluginStore, + ontology: PluginResource, +): Promise> { + const listed = asList(ontology.get(PROPERTIES)); + const byShortname = new Map(); + + for (const subject of listed) { + const shortname = (await store.getResource(subject)).get(SHORTNAME); + if (typeof shortname === 'string') byShortname.set(shortname, subject); + } + + const created: string[] = []; + const out = {} as Record; + + for (const spec of PROPERTY_SPECS) { + let subject = byShortname.get(spec.shortname); + + if (!subject) { + const property = await store.newResource({ + parent: ontology.subject, + isA: [PROPERTY_CLASS], + propVals: { + [SHORTNAME]: spec.shortname, + [NAME]: spec.name, + [DESCRIPTION]: spec.description, + [DATATYPE]: spec.datatype, + }, + }); + subject = property.subject; + created.push(subject); + } + + out[spec.key] = subject; + } + + if (created.length > 0) + await ontology.set(PROPERTIES, [...listed, ...created]).save(); + + return out; +} + +/** The app's own ontology: the App's default ontology, as `createApp` sets it. */ +async function appOntology( + store: PluginStore, + app: string, +): Promise { + const own = (await store.getResource(app)).get(DEFAULT_ONTOLOGY); + if (typeof own === 'string') return store.getResource(own); + throw new Error('This app has no ontology of its own to add fields to.'); +} + +/** + * An App property of the drive's plugin vocabulary (`renders`, + * `row-extras`), found by shortname among what the App's class recommends; + * their subjects are minted per drive. + */ +async function appProperty( + store: PluginStore, + app: PluginResource, + shortname: string, +): Promise { + for (const klass of asList(app.get(IS_A))) { + const resource = await store.getResource(klass).catch(() => undefined); + + for (const subject of asList(resource?.get(RECOMMENDS) ?? [])) { + const term = await store.getResource(subject).catch(() => undefined); + if (term?.get(SHORTNAME) === shortname) return subject; + } + } + + return undefined; +} + +/** Adds `wanted` to the list `property` holds on `resource`; true if changed. */ +function include( + resource: PluginResource, + property: string | undefined, + wanted: string[], +): boolean { + if (!property) return false; + const list = asList(resource.get(property) ?? []); + const missing = wanted.filter(s => !list.includes(s)); + if (!missing.length) return false; + resource.set(property, [...list, ...missing]); + + return true; +} + +/** The table shown is not this app's own (it was added as a view there). */ +export class OtherTable extends Error { + constructor() { + super( + 'This is another Issue table. The Todoist app imports only into its own table.', + ); + this.name = 'OtherTable'; + } +} + +/** Whether the table shown is the app's own, not one it was added to as a view. */ +export async function showsOwnTable(store: PluginStore): Promise { + const data = await store.getData(); + if (!data?.table) return true; + + return ( + (await store.getResource(data.table)).get(PARENT) === (await store.getApp()) + ); +} + +/** What sync.ts writes with: the app's subjects. */ +export interface Drive { + app: string; + table: string; + /** Always `ISSUE_V1`. */ + rowClass: string; + properties: Record; +} + +/** + * Creates (or finds) the app's properties, makes the app a view of + * `issue-v1` (`renders`, `row-extras`, the table's `classtype`) and names + * the table. Idempotent. Throws `OtherTable` when the table shown is not the + * app's own; `renders` and `row-extras` are set first, so the App is a view + * of the class either way. + */ +export async function provision(store: PluginStore): Promise { + const app = await store.getApp(); + const data = await store.getData(); + if (!data?.table) throw new Error('This app has no table to import into.'); + const ontology = await appOntology(store, app); + const properties = await ensureProperties(store, ontology); + + const resource = await store.getResource(app); + const renders = include( + resource, + await appProperty(store, resource, 'renders'), + [ISSUE_V1], + ); + const declared = include( + resource, + await appProperty(store, resource, 'row-extras'), + ROW_EXTRAS.map(key => properties[key]), + ); + if (renders || declared) await resource.save(); + + const table = await store.getResource(data.table); + if (table.get(PARENT) !== app) throw new OtherTable(); + const retype = table.get(CLASSTYPE) !== ISSUE_V1; + const rename = table.get(NAME) !== TABLE_NAME; + if (retype) table.set(CLASSTYPE, ISSUE_V1); + if (rename) table.set(NAME, TABLE_NAME); + if (retype || rename) await table.save(); + + return { app, table: data.table, rowClass: ISSUE_V1, properties }; +} + +/** The time of the last complete read, or undefined before the first. */ +export async function lastSync( + store: PluginStore, + drive: Drive, +): Promise { + const value = (await store.getResource(drive.app)).get( + drive.properties.lastSync, + ); + + return typeof value === 'string' && value ? value : undefined; +} + +export async function recordSync( + store: PluginStore, + drive: Drive, + at: string, +): Promise { + const app = await store.getResource(drive.app); + if (app.get(drive.properties.lastSync) === at) return; + await app.set(drive.properties.lastSync, at).save(); +} diff --git a/integrations/issue-tracker/todoist-app/fakeStore.ts b/integrations/issue-tracker/todoist-app/fakeStore.ts new file mode 100644 index 000000000..d85084588 --- /dev/null +++ b/integrations/issue-tracker/todoist-app/fakeStore.ts @@ -0,0 +1,202 @@ +// @wc-ignore-file +/** + * An in-memory `PluginStore` for tests, shaped after view-client.js and laid + * out the way `createApp` lays out an app (app -> ontology -> row class, and + * app -> table), like ../app/fakeStore.ts. `proxy` answers from the same + * Todoist fixture the mock integration proxy serves + * (`../fixtures/todoist/scenario.mjs`), whose drivers a test calls directly + * on `todoist`. Test-only; not bundled. + */ +import { todoistFixture } from '../fixtures/todoist/scenario.mjs'; +import { + CLASSTYPE, + DEFAULT_ONTOLOGY, + IS_A, + NAME, + PARENT, + PROPERTIES, + RECOMMENDS, + SHORTNAME, +} from './drive.js'; +import type { + HostProxy, + HostProxyRequest, + JSONValue, + PluginResource, + PluginStore, +} from './store.js'; + +export const APP = 'did:ad:app'; +export const ONTOLOGY = 'did:ad:ontology'; +export const ROW_CLASS = 'did:ad:class-item'; +export const TABLE = 'did:ad:table-items'; +/** The drive's plugin vocabulary, as `pluginSchema()` mints it per drive. */ +export const APP_CLASS = 'did:ad:plugin-class-app'; +export const RENDERS = 'did:ad:plugin-renders'; +export const ROW_EXTRAS = 'did:ad:plugin-row-extras'; +/** Someone else's issue-v1 table the app can be added to as a view. */ +export const OTHER_TABLE = 'did:ad:table-theirs'; + +export interface FakeStore extends PluginStore { + readonly resources: Map>; + readonly writes: { op: 'create' | 'save'; subject: string }[]; + readonly calls: HostProxyRequest[]; + readonly todoist: ReturnType; + /** Makes every relayed call throw with this host error until cleared. */ + fail?: string; +} + +export function fakeStore({ + connected = true, + existing = false, + relay = true, + table = TABLE, +}: { + /** The table the app is shown on; OTHER_TABLE is a view on someone's table. */ + table?: string; + connected?: boolean; + /** `proxy.connect` resolves `connected` (the host's "Use existing connection"). */ + existing?: boolean; + relay?: boolean; +} = {}): FakeStore { + const resources = new Map>([ + [ + APP, + { + [NAME]: 'New app', + [IS_A]: [APP_CLASS], + [DEFAULT_ONTOLOGY]: ONTOLOGY, + [RENDERS]: [ROW_CLASS], + }, + ], + [APP_CLASS, { [SHORTNAME]: 'app', [RECOMMENDS]: [RENDERS, ROW_EXTRAS] }], + [RENDERS, { [SHORTNAME]: 'renders' }], + [ROW_EXTRAS, { [SHORTNAME]: 'row-extras' }], + [ONTOLOGY, { [PARENT]: APP, [PROPERTIES]: [] }], + [ROW_CLASS, { [PARENT]: ONTOLOGY, [NAME]: 'Item', [RECOMMENDS]: [NAME] }], + [TABLE, { [PARENT]: APP, [NAME]: 'Items', [CLASSTYPE]: ROW_CLASS }], + [ + OTHER_TABLE, + { + [PARENT]: 'did:ad:someone', + [NAME]: 'Their issues', + [CLASSTYPE]: ROW_CLASS, + }, + ], + ]); + const writes: FakeStore['writes'] = []; + const calls: HostProxyRequest[] = []; + const todoist = todoistFixture(); + let next = 0; + + const wrap = ( + subject: string, + stored: Record, + ): PluginResource => { + const props = structuredClone(stored); + const removed = new Set(); + + return { + subject, + get props() { + return { ...props }; + }, + get: property => props[property], + set(property, value) { + props[property] = value; + removed.delete(property); + + return this; + }, + remove(property) { + delete props[property]; + removed.add(property); + + return this; + }, + async save() { + const saved = { ...resources.get(subject), ...structuredClone(props) }; + for (const property of removed) delete saved[property]; + removed.clear(); + resources.set(subject, saved); + writes.push({ op: 'save', subject }); + + return this; + }, + async destroy() { + resources.delete(subject); + }, + }; + }; + + const proxy: HostProxy = { + async request(request) { + calls.push(request); + if (fake.fail) throw new Error(fake.fail); + const result = todoist.request( + request.method ?? 'GET', + new URL(`/proxy/todoist${request.path}`, 'https://proxy.example'), + ); + + return { status: result.status, headers: {}, body: result.body }; + }, + async connections({ platform }) { + return connected ? [{ connectionId: 'c1', platform }] : []; + }, + connect: ({ platform }) => { + if (!existing) return new Promise(() => {}); + connected = true; + + return Promise.resolve({ + status: 'connected' as const, + connectionId: 'c1', + platform, + }); + }, + }; + + const fake: FakeStore = { + resources, + writes, + calls, + todoist, + getApp: async () => APP, + getData: async () => { + const classtype = resources.get(table)?.[CLASSTYPE]; + + return { + table, + ...(typeof classtype === 'string' ? { rowClass: classtype } : {}), + }; + }, + async getResource(subject) { + const stored = resources.get(subject); + if (!stored) throw new Error(`No resource ${subject}`); + + return wrap(subject, stored); + }, + async query({ property, value }) { + const out: string[] = []; + for (const [subject, props] of resources) + if (props[property] === value) out.push(subject); + + return out; + }, + async newResource({ parent, isA = [], propVals = {} } = {}) { + const subject = `did:ad:new-${++next}`; + const stored = { + ...structuredClone(propVals), + [PARENT]: parent ?? APP, + [IS_A]: isA, + }; + resources.set(subject, stored); + writes.push({ op: 'create', subject }); + + return wrap(subject, stored); + }, + subscribe: () => () => {}, + ...(relay ? { proxy } : {}), + }; + + return fake; +} diff --git a/integrations/issue-tracker/todoist-app/main.ts b/integrations/issue-tracker/todoist-app/main.ts new file mode 100644 index 000000000..806e9da6e --- /dev/null +++ b/integrations/issue-tracker/todoist-app/main.ts @@ -0,0 +1,99 @@ +// @wc-ignore-file +/** + * The Todoist drive-app entry point (read-only active tasks, #99's host + * journey). The host's generated shell does + * `const plugin = await import(js_url); await plugin.view({ root, store })`, + * so this module exports `view` and does not render on import. One module, + * no stylesheet, no network access of its own: every call goes through the + * host's proxy client. Plain DOM, no framework: a heading, a status line, + * the connect and sync buttons, and the table's tasks with their presence. + */ +import { createController, describe, type ViewState } from './controller.js'; +import type { ViewArgs } from './store.js'; +import type { TaskRow } from './sync.js'; + +const COLUMNS: [string, (t: TaskRow) => string][] = [ + ['Task', t => t.name], + ['Status', t => (t.done ? 'Done' : 'Todo')], + ['Presence', t => t.presence], + ['Due', t => t.dueDay ?? ''], + ['Priority', t => t.priority ?? ''], + ['Project', t => t.project ?? ''], + ['Last seen', t => t.lastSeen ?? ''], +]; + +export async function view({ root, store }: ViewArgs): Promise { + const doc = root.ownerDocument; + + const el = (tag: K, text = '') => { + const node = doc.createElement(tag); + node.textContent = text; + + return node; + }; + + const heading = el('h1', 'Todoist'); + const status = el('p'); + status.setAttribute('role', 'status'); + const connect = el('button', 'Connect Todoist'); + const sync = el('button', 'Sync now'); + for (const button of [connect, sync]) button.type = 'button'; + const note = el( + 'p', + 'Read-only: closing or editing a task here is not sent to Todoist. A task that stops appearing is checked by id and shown as completed only when Todoist says so.', + ); + const table = el('table'); + const head = el('thead'); + const headRow = el('tr'); + for (const [label] of COLUMNS) headRow.append(el('th', label)); + head.append(headRow); + const body = el('tbody'); + table.append(head, body); + table.setAttribute('aria-label', 'Imported tasks'); + root.style.fontFamily = 'system-ui, sans-serif'; + root.style.padding = '1rem'; + table.style.borderCollapse = 'collapse'; + table.style.marginTop = '1rem'; + root.replaceChildren(heading, status, connect, sync, note, table); + + const render = (state: ViewState) => { + status.textContent = describe(state); + connect.hidden = !( + state.kind === 'disconnected' || + (state.kind === 'error' && !state.connection) + ); + const known = + state.kind === 'synced' || + state.kind === 'syncing' || + (state.kind === 'error' && !!state.connection); + sync.hidden = !known; + sync.disabled = state.kind === 'syncing'; + const tasks = 'tasks' in state ? state.tasks : []; + table.hidden = tasks.length === 0; + body.replaceChildren( + ...tasks.map(task => { + const row = el('tr'); + row.dataset.task = task.taskId; + row.dataset.subject = task.subject; + row.dataset.presence = task.presence; + + for (const [, cell] of COLUMNS) { + const td = el('td', cell(task)); + td.style.padding = '0.25rem 0.75rem 0.25rem 0'; + row.append(td); + } + + return row; + }), + ); + }; + + const controller = createController(store, render); + render(controller.state()); + connect.addEventListener('click', () => void controller.connect()); + sync.addEventListener('click', () => void controller.sync()); + + await controller.load().catch((error: unknown) => { + status.textContent = `Could not load: ${error instanceof Error ? error.message : String(error)}`; + }); +} diff --git a/integrations/issue-tracker/todoist-app/package.json b/integrations/issue-tracker/todoist-app/package.json new file mode 100644 index 000000000..6cb0e6392 --- /dev/null +++ b/integrations/issue-tracker/todoist-app/package.json @@ -0,0 +1,7 @@ +{ + "name": "@atomic-integrations/todoist-app", + "private": true, + "version": "0.1.0", + "type": "module", + "description": "Todoist drive app (read-only active tasks into the shared issue-v1 class). Records only the version its catalog entry and apps/todoist//ui.js carry (integrations/tooling/apps.mjs APP_FOLDERS); no npm dependencies. Its version is its own, not the GitHub issues app's in ../app/package.json." +} diff --git a/integrations/issue-tracker/todoist-app/read.ts b/integrations/issue-tracker/todoist-app/read.ts new file mode 100644 index 000000000..fa65c529d --- /dev/null +++ b/integrations/issue-tracker/todoist-app/read.ts @@ -0,0 +1,193 @@ +// @wc-ignore-file +/** + * Read-only access to the three Todoist API v1 operations the app uses, all + * `GET` and all allowed by the proxy's `data:read` Todoist catalog: + * `/api/v1/projects`, `/api/v1/tasks` (active tasks, paged by cursor) and + * `/api/v1/tasks/{task_id}` (the by-id check of ../todoist.ts). Nothing here + * writes to Todoist, and nothing here holds a credential: a `TodoistGet` is + * the host's proxy relay (see `relayGet` in sync.ts). + * + * The result is the `FetchedPlatform` shape ../todoist.ts consumes. A read + * that stops early (the page cap) is reported in `errors`, which that module + * treats as a partial read: it then draws no conclusion from any task's + * absence. A page that fails outright throws instead, and the caller writes + * nothing. Verified against the synthetic fixture only (fixtures/todoist/), + * not against Todoist (#46). + */ +import { Datatype } from '../../../browser/lib/src/index.js'; +import type { JSONValue } from '../../../browser/lib/src/value.js'; +import type { + FetchedPlatform, + FetchedRecord, +} from '../../localthought/schema.js'; +import { TODOIST_PLATFORM, type TodoistLookup } from '../todoist.js'; + +export const UPSTREAM = 'https://api.todoist.com/api/v1'; +/** Todoist's documented maximum `limit`. */ +export const PAGE_SIZE = 200; +/** 50 pages of 200: past this the read is reported partial, not continued. */ +export const MAX_PAGES = 50; + +export interface TodoistResponse { + status: number; + body: unknown; +} + +/** One GET of a provider path under UPSTREAM, e.g. `/api/v1/tasks?limit=200`. */ +export type TodoistGet = (path: string) => Promise; + +export class TodoistError extends Error { + constructor( + message: string, + readonly status?: number, + ) { + super(message); + } +} + +type Row = Record; + +const isRow = (value: unknown): value is Row => + !!value && typeof value === 'object' && !Array.isArray(value); + +function page(response: TodoistResponse, what: string) { + if (response.status === 401 || response.status === 403) + throw new TodoistError( + `Todoist refused ${what} (${response.status}); reconnect Todoist.`, + response.status, + ); + if (response.status !== 200) + throw new TodoistError( + `Todoist answered ${response.status} for ${what}.`, + response.status, + ); + const body = response.body; + if (!isRow(body) || !Array.isArray(body.results)) + throw new TodoistError(`Todoist sent no results for ${what}.`); + const cursor = body.next_cursor; + + return { + rows: body.results.filter(isRow), + next: typeof cursor === 'string' && cursor ? cursor : undefined, + }; +} + +/** + * Every row of a collection, all pages read before returning. Returns the + * rows and, when the page cap stopped the read, why: the read is then + * partial. A row seen twice (it moved between pages) is kept once, with its + * last-read value. + */ +async function collection( + get: TodoistGet, + path: string, + { pageSize = PAGE_SIZE, maxPages = MAX_PAGES } = {}, +): Promise<{ rows: Row[]; partial?: string }> { + const byId = new Map(); + let cursor: string | undefined; + + for (let n = 1; ; n++) { + if (n > maxPages) + return { + rows: [...byId.values()], + partial: `Stopped reading ${path} after ${maxPages} pages of ${pageSize}; Todoist kept sending a next page.`, + }; + const query = new URLSearchParams({ limit: String(pageSize) }); + if (cursor) query.set('cursor', cursor); + const { rows, next } = page( + await get(`${path}?${query}`), + `${path.split('/').pop()} page ${n}`, + ); + for (const row of rows) + if (typeof row.id === 'string' && row.id) byId.set(row.id, row); + if (!next) return { rows: [...byId.values()] }; + cursor = next; + } +} + +/** Project id -> name, for the row's project column. */ +export async function readProjects( + get: TodoistGet, + options?: { pageSize?: number; maxPages?: number }, +): Promise> { + const { rows } = await collection(get, '/api/v1/projects', options); + + return new Map( + rows.flatMap(row => + typeof row.id === 'string' && typeof row.name === 'string' + ? [[row.id, row.name]] + : [], + ), + ); +} + +/** + * The active tasks as a `FetchedPlatform` for ../todoist.ts: one `task` + * class term (what `todoistProjection` keys on) and one record per task, + * with the provider's fields as its values. `errors` is set when the read + * was partial. + */ +export async function readActiveTasks( + get: TodoistGet, + options?: { pageSize?: number; maxPages?: number }, +): Promise { + const { rows, partial } = await collection(get, '/api/v1/tasks', options); + const records: FetchedRecord[] = rows.map(row => ({ + resource: 'task', + namespace: TODOIST_PLATFORM, + id: row.id as string, + name: row.id as string, + values: row, + })); + + return { + platform: TODOIST_PLATFORM, + ontology: { + description: 'Todoist API v1, as the proxy serves it (read-only).', + terms: [ + { + path: 'urn:atomic:todoist:task', + kind: 'class', + shortname: 'task', + description: 'An active task in the connected Todoist account.', + datatype: Datatype.STRING, + requires: [], + recommends: [], + }, + ], + }, + records, + ...(partial ? { errors: [partial] } : {}), + }; +} + +/** + * `GET /api/v1/tasks/{id}` for each absent task, as ../todoist.ts's + * `TodoistLookup`s: the status and body as answered, or the error when the + * call itself failed (which that module reads as `unconfirmed`). One at a + * time; there are rarely more than a few. + */ +export async function lookupTasks( + get: TodoistGet, + ids: string[], +): Promise { + const out: TodoistLookup[] = []; + + for (const id of ids) { + try { + const response = await get(`/api/v1/tasks/${encodeURIComponent(id)}`); + out.push({ + id, + status: response.status, + body: response.body as JSONValue, + }); + } catch (error) { + out.push({ + id, + error: error instanceof Error ? error.message : String(error), + }); + } + } + + return out; +} diff --git a/integrations/issue-tracker/todoist-app/store.ts b/integrations/issue-tracker/todoist-app/store.ts new file mode 100644 index 000000000..b553a9d28 --- /dev/null +++ b/integrations/issue-tracker/todoist-app/store.ts @@ -0,0 +1,136 @@ +// @wc-ignore-file +/** + * The `store` a drive plugin's `view({ root, store })` receives from the host + * (atomic-server `server/src/plugins/assets/view-client.js`). It is never + * bundled here. The types are kept by hand in step with that file and with + * the other apps' copies (this is ../app/store.ts, the GitHub issues app's, + * unchanged); there is no package to import them from yet, and sharing one + * copy is a maintainer decision (per-plugin containment). If they disagree, + * view-client.js is ground truth. + * + * `proxy` (ontola/atomic-plugins#54 phase 2): the frame names a platform and + * a connection id, never a credential. view-client.js makes an Ed25519 key in + * the frame's memory, gets a short-lived capability for it from the page + * (signed with the user's key, after the page checked the connection is + * delegated to this app), and calls the integration proxy directly, signing + * each request with that key. It is feature-detected, never assumed. Without it + * the app says so and fetches nothing. + */ + +export type JSONValue = + | string + | number + | boolean + | null + | undefined + | { [key: string]: JSONValue } + | JSONValue[]; + +export interface DataRef { + table: string; + rowClass?: string; +} + +export interface PluginResource { + readonly subject: string; + readonly props: Record; + get(property: string): JSONValue; + set(property: string, value: JSONValue): PluginResource; + remove(property: string): PluginResource; + save(): Promise; + destroy(): Promise; +} + +/** One proxy call, made by the host's frame client. Carries a connection reference, never a credential. */ +export interface HostProxyRequest { + platform: string; + connectionId: string; + /** The provider path after the proxy's `/proxy//`, e.g. `/v1/search`. */ + path: string; + method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; + query?: Record; + /** JSON text. */ + body?: string; +} + +export interface HostProxyResponse { + status: number; + /** Lower-cased, and only an allowlist (`link`, `retry-after`, `etag`, `content-type`). */ + headers?: Record; + /** Parsed JSON when the response parses, the raw text otherwise. */ + body: unknown; +} + +/** What `proxy.connect` resolves to, when it resolves. */ +export type ConnectResult = + | { status: 'cancelled' } + | { status: 'connected'; connectionId: string; platform: string }; + +export interface HostProxy { + request(request: HostProxyRequest): Promise; + /** Connections for `platform` the person delegated to this app, at the proxy. */ + connections(args: { + platform: string; + }): Promise<{ connectionId: string; platform: string }[]>; + /** + * Shows the host's consent bar. Resolves `connected` when the person picks + * a connection they already have (the host delegates it to this app; no + * reload), `cancelled` when they cancel. Connecting a new account sends the + * page to the proxy and back, which reloads this view, so then it never + * settles. + */ + connect(args: { platform: string }): Promise; + /** + * Takes this app's delegation off the platform's connections; the + * connections themselves stay (atomic-server pin 007869464). Optional: + * older hosts lack it. + */ + disconnect?(args: { platform: string }): Promise<{ + status: 'disconnected'; + platform: string; + connectionIds: string[]; + }>; +} + +/** Whether the host is drawn light or dark (`store.getTheme()`). */ +export type ColorScheme = 'light' | 'dark'; + +export interface PluginStore { + getApp(): Promise; + getData(): Promise; + getResource(subject: string): Promise; + query(args: { property: string; value: string }): Promise; + newResource(args?: { + parent?: string; + isA?: string[]; + propVals?: Record; + }): Promise; + /** `handler` takes no argument; re-fetch via getResource for the new data. */ + subscribe(subject: string, handler: () => void): () => void; + proxy?: HostProxy; + /* + * Since atomic-server pin 007869464, feature-detected (older hosts lack + * them; the app then falls back as noted where it calls them). + */ + /** Up to 100 subjects in one round trip, in the order asked. */ + getMany?( + subjects: string[], + ): Promise<(PluginResource | { subject: string; error: string })[]>; + /** Opens an http(s) URL after the host shows the person where it goes. */ + openExternal?(url: string): Promise<{ status: 'opened' | 'cancelled' }>; + /** Shows a resource in the host page, leaving this app. */ + openResource?( + subject: string, + ): Promise<{ status: 'opened'; subject: string }>; + /** The host's light/dark setting. */ + getTheme?(): { colorScheme?: ColorScheme }; + /** Calls back when the person switches light/dark; returns a stop function. */ + onThemeChange?( + handler: (theme: { colorScheme?: ColorScheme }) => void, + ): () => void; +} + +export interface ViewArgs { + root: HTMLElement; + store: PluginStore; +} diff --git a/integrations/issue-tracker/todoist-app/sync.test.ts b/integrations/issue-tracker/todoist-app/sync.test.ts new file mode 100644 index 000000000..daa6b2469 --- /dev/null +++ b/integrations/issue-tracker/todoist-app/sync.test.ts @@ -0,0 +1,417 @@ +// @wc-ignore-file +/** + * The import pass against the in-memory store and the synthetic Todoist + * fixture: provisioning as a view of issue-v1, the first import, a refresh + * that writes no row, and #99's disappearance behaviour (completed, deleted, + * unavailable, unconfirmed, partial read, reappearance) as the host runs it. + */ +import { describe, expect, it } from 'vitest'; +import { createController, describeSummary } from './controller.js'; +import { + CLASSTYPE, + ISSUE_V1, + NAME, + OtherTable, + PROPERTIES, + provision, + SHORTNAME, + TABLE_NAME, + TAG_DONE, + TAG_TODO, + TASK_BODY, + TASK_DUE_DATE, + TASK_STATUS, +} from './drive.js'; +import { + APP, + fakeStore, + ONTOLOGY, + OTHER_TABLE, + RENDERS, + ROW_EXTRAS, + TABLE, +} from './fakeStore.js'; +import { TodoistError } from './read.js'; +import { relayGet, syncTasks } from './sync.js'; + +const T1 = '2026-03-01T10:00:00.000Z'; +const T2 = '2026-03-01T11:00:00.000Z'; +const T3 = '2026-03-01T12:00:00.000Z'; +const T4 = '2026-03-01T13:00:00.000Z'; + +async function setUp() { + const store = fakeStore(); + const drive = await provision(store); + const get = relayGet(store.proxy!, { + platform: 'todoist', + connectionId: 'c1', + }); + const sync = (now: string, read?: { maxPages?: number }) => + syncTasks(store, get, drive, { now: () => now, read }); + + const rowOf = (taskId: string) => { + for (const [subject, props] of store.resources) + if (props[drive.properties.taskId] === taskId) + return { subject, ...props }; + + throw new Error(`no row for ${taskId}`); + }; + + const p = drive.properties; + + return { store, drive, sync, rowOf, p }; +} + +describe('provisioning', () => { + it('makes the app a view of issue-v1 and adds its extras, once', async () => { + const { store, drive, p } = await setUp(); + const app = store.resources.get(APP)!; + expect(app[RENDERS]).toContain(ISSUE_V1); + expect(app[ROW_EXTRAS]).toEqual([ + p.taskId, + p.presence, + p.lastSeen, + p.priority, + p.project, + p.source, + ]); + const table = store.resources.get(TABLE)!; + expect(table[CLASSTYPE]).toBe(ISSUE_V1); + expect(table[NAME]).toBe(TABLE_NAME); + expect(drive.rowClass).toBe(ISSUE_V1); + const listed = store.resources.get(ONTOLOGY)![PROPERTIES] as string[]; + expect(listed).toHaveLength(7); + expect(listed.map(s => store.resources.get(s)![SHORTNAME])).toContain( + 'todoist-task-id', + ); + + const before = store.writes.length; + const again = await provision(store); + expect(again).toEqual(drive); + expect(store.writes.length).toBe(before); + }); + + it('refuses another Issue table, after declaring what it renders', async () => { + const store = fakeStore({ table: OTHER_TABLE }); + await expect(provision(store)).rejects.toBeInstanceOf(OtherTable); + expect(store.resources.get(APP)![RENDERS]).toContain(ISSUE_V1); + expect(store.resources.get(OTHER_TABLE)![CLASSTYPE]).not.toBe(ISSUE_V1); + }); +}); + +describe('import', () => { + it('writes every active task as an issue-v1 row with shared fields and extras', async () => { + const { store, sync, rowOf, p } = await setUp(); + const summary = await sync(T1); + expect(summary).toMatchObject({ + total: 5, + added: 5, + updated: 0, + unchanged: 0, + checked: 0, + complete: true, + presence: { active: 5, completed: 0 }, + }); + expect(describeSummary(summary)).toBe( + '5 tasks (5 added, 0 updated, 0 unchanged); 5 active.', + ); + + const plants = rowOf('synthetic-task-1'); + expect(plants).toMatchObject({ + [NAME]: 'Water the synthetic plants', + [TASK_STATUS]: [TAG_TODO], + [TASK_DUE_DATE]: '2026-03-02', + [p.presence]: 'active', + [p.priority]: 'Urgent', + [p.project]: 'Inbox', + }); + expect(plants).not.toHaveProperty(TASK_BODY); + expect(plants).not.toHaveProperty(p.lastSeen); + const source = JSON.parse(plants[p.source] as string); + expect(source).toMatchObject({ + id: 'synthetic-task-1', + checked: false, + done: false, + presence: 'active', + 'due-day': '2026-03-02', + }); + expect(source).not.toHaveProperty('last-seen'); + + const plumber = rowOf('synthetic-task-2'); + expect(plumber).toMatchObject({ + [TASK_BODY]: 'Ask about the imaginary leak under the sink.', + // The day of due.datetime. + [TASK_DUE_DATE]: '2026-03-03', + [p.priority]: 'High', + }); + expect(rowOf('synthetic-task-3')).toMatchObject({ + [p.project]: 'Synthetic house', + [p.priority]: 'Medium', + }); + expect(rowOf('synthetic-task-5')).not.toHaveProperty(TASK_DUE_DATE); + + // The read's time is on the App, not on the rows. + expect(store.resources.get(APP)![p.lastSync]).toBe(T1); + }); + + it('refreshes without writing any row when nothing changed', async () => { + const { store, sync } = await setUp(); + await sync(T1); + const rows = new Map( + [...store.resources].filter(([, props]) => props[TASK_STATUS]), + ); + const before = store.writes.length; + + expect(await sync(T2)).toMatchObject({ + added: 0, + updated: 0, + unchanged: 5, + }); + const since = store.writes.slice(before); + expect(since.map(w => w.subject)).toEqual([APP]); + for (const [subject, props] of rows) + expect(store.resources.get(subject)).toEqual(props); + }); + + it('leaves a hand-made row alone', async () => { + const { store, sync } = await setUp(); + const local = await store.newResource({ + parent: TABLE, + isA: [ISSUE_V1], + propVals: { [NAME]: 'Written in the table' }, + }); + expect(await sync(T1)).toMatchObject({ total: 5, added: 5 }); + expect(store.resources.get(local.subject)).toEqual({ + ...local.props, + }); + }); + + it('writes nothing when a page fails, and names a revoked connection', async () => { + const { store, sync } = await setUp(); + store.todoist.failNext(1, 503, 'list'); + const before = store.writes.length; + await expect(sync(T1)).rejects.toThrow('Todoist answered 503'); + expect(store.writes.length).toBe(before); + + store.todoist.failNext(1, 401, 'list'); + await expect(sync(T1)).rejects.toSatisfy( + (e: unknown) => + e instanceof TodoistError && /reconnect Todoist/.test(e.message), + ); + }); +}); + +describe('a task that stops appearing (#99)', () => { + it('is looked up by id once and closed only when Todoist says completed', async () => { + const { store, sync, rowOf, p } = await setUp(); + await sync(T1); + store.todoist.completeTask('synthetic-task-1'); + const calls = store.calls.length; + + const summary = await sync(T2); + expect(summary).toMatchObject({ + updated: 1, + unchanged: 4, + checked: 1, + presence: { active: 4, completed: 1 }, + }); + expect(describeSummary(summary)).toContain('4 active, 1 completed'); + expect( + store.calls.slice(calls).filter(c => /\/tasks\/[^?]/.test(c.path)), + ).toEqual([ + expect.objectContaining({ path: '/api/v1/tasks/synthetic-task-1' }), + ]); + expect(rowOf('synthetic-task-1')).toMatchObject({ + [TASK_STATUS]: [TAG_DONE], + [p.presence]: 'completed', + [p.lastSeen]: T2, + // Its other columns stay as the task was last returned. + [NAME]: 'Water the synthetic plants', + [TASK_DUE_DATE]: '2026-03-02', + }); + + // Settled: not checked again, and unchanged on the next pass. + const again = await sync(T3); + expect(again).toMatchObject({ checked: 0, updated: 0, unchanged: 5 }); + }); + + it('marks deleted and unavailable without closing, keeping last values and when they were seen', async () => { + const { store, sync, rowOf, p } = await setUp(); + await sync(T1); + store.todoist.deleteTask('synthetic-task-2'); + store.todoist.removeTask('synthetic-task-3'); + + expect(await sync(T2)).toMatchObject({ + updated: 2, + checked: 2, + presence: { active: 3, deleted: 1, unavailable: 1 }, + }); + expect(rowOf('synthetic-task-2')).toMatchObject({ + [TASK_STATUS]: [TAG_TODO], + [TASK_BODY]: 'Ask about the imaginary leak under the sink.', + [p.presence]: 'deleted', + // Last returned by the complete read at T1, not by this pass. + [p.lastSeen]: T1, + }); + expect(rowOf('synthetic-task-3')).toMatchObject({ + [TASK_STATUS]: [TAG_TODO], + [p.presence]: 'unavailable', + [p.lastSeen]: T1, + }); + // Nothing is removed. + expect([...store.resources.values()].filter(r => r[p.taskId]).length).toBe( + 5, + ); + + // Settled presences are not checked again. + expect(await sync(T3)).toMatchObject({ checked: 0, updated: 0 }); + }); + + it('is unconfirmed when the check fails, and checked again next time', async () => { + const { store, sync, rowOf, p } = await setUp(); + await sync(T1); + store.todoist.completeTask('synthetic-task-4'); + store.todoist.failNext(1, 503, 'lookup'); + + expect(await sync(T2)).toMatchObject({ + checked: 1, + presence: { active: 4, unconfirmed: 1 }, + }); + expect(rowOf('synthetic-task-4')).toMatchObject({ + [TASK_STATUS]: [TAG_TODO], + [p.presence]: 'unconfirmed', + [p.lastSeen]: T1, + [TASK_DUE_DATE]: '2026-03-20', + }); + + expect(await sync(T3)).toMatchObject({ + checked: 1, + presence: { active: 4, completed: 1 }, + }); + expect(rowOf('synthetic-task-4')).toMatchObject({ + [TASK_STATUS]: [TAG_DONE], + [p.presence]: 'completed', + [p.lastSeen]: T3, + }); + }); + + it('draws nothing from a partial read', async () => { + const { store, sync, rowOf, p } = await setUp(); + await sync(T1); + store.todoist.completeTask('synthetic-task-1'); + const calls = store.calls.length; + + // Three tasks per fixture page: one page is a partial read. + const summary = await sync(T2, { maxPages: 1 }); + expect(summary).toMatchObject({ + complete: false, + checked: 0, + updated: 0, + presence: { active: 5 }, + }); + expect(describeSummary(summary)).toContain('The read was partial'); + expect( + store.calls.slice(calls).some(c => /\/tasks\/[^?]/.test(c.path)), + ).toBe(false); + expect(rowOf('synthetic-task-1')).toMatchObject({ + [TASK_STATUS]: [TAG_TODO], + [p.presence]: 'active', + }); + // The App's last complete read stays T1. + expect(store.resources.get(APP)![p.lastSync]).toBe(T1); + + expect(await sync(T3)).toMatchObject({ + checked: 1, + presence: { active: 4, completed: 1 }, + }); + }); + + it('is active again when it reappears', async () => { + const { store, sync, rowOf, p } = await setUp(); + await sync(T1); + store.todoist.completeTask('synthetic-task-1'); + await sync(T2); + store.todoist.reopenTask('synthetic-task-1'); + + expect(await sync(T3)).toMatchObject({ + reappeared: 1, + updated: 1, + presence: { active: 5, completed: 0 }, + }); + const row = rowOf('synthetic-task-1'); + expect(row).toMatchObject({ + [TASK_STATUS]: [TAG_TODO], + [p.presence]: 'active', + }); + expect(row).not.toHaveProperty(p.lastSeen); + expect(await sync(T4)).toMatchObject({ updated: 0, unchanged: 5 }); + }); +}); + +describe('controller', () => { + const states: string[] = []; + const track = (store: ReturnType) => + createController(store, s => states.push(s.kind), { now: () => T1 }); + + it('syncs on load with a connection and lists the table', async () => { + states.length = 0; + const store = fakeStore(); + const controller = track(store); + const { syncing } = await controller.load(); + await syncing; + const state = controller.state(); + expect(state.kind).toBe('synced'); + if (state.kind !== 'synced') return; + expect(state.summary.added).toBe(5); + expect(state.tasks.map(t => t.name)).toEqual([ + 'Call the invented plumber', + 'Paint the fictional fence', + 'Return the made-up library books', + 'Sort the pretend attic', + 'Water the synthetic plants', + ]); + expect(state.tasks[0]).toMatchObject({ + taskId: 'synthetic-task-2', + done: false, + presence: 'active', + dueDay: '2026-03-03', + priority: 'High', + project: 'Inbox', + }); + expect(states).toEqual(['syncing', 'synced']); + }); + + it('is disconnected without a connection, and syncs after an existing one is picked', async () => { + const store = fakeStore({ connected: false, existing: true }); + const controller = track(store); + await controller.load(); + expect(controller.state().kind).toBe('disconnected'); + await controller.connect(); + expect(controller.state().kind).toBe('synced'); + }); + + it('reports another table and a host without the proxy client', async () => { + const other = track(fakeStore({ table: OTHER_TABLE })); + await other.load(); + expect(other.state().kind).toBe('other-table'); + + const bare = track(fakeStore({ relay: false })); + await bare.load(); + expect(bare.state().kind).toBe('no-relay'); + }); + + it('keeps the imported rows when a refresh fails', async () => { + const store = fakeStore(); + const controller = track(store); + await ( + await controller.load() + ).syncing; + store.fail = 'host offline'; + await controller.sync(); + const state = controller.state(); + expect(state.kind).toBe('error'); + if (state.kind !== 'error') return; + expect(state.message).toContain('host offline'); + expect(state.tasks).toHaveLength(5); + }); +}); diff --git a/integrations/issue-tracker/todoist-app/sync.ts b/integrations/issue-tracker/todoist-app/sync.ts new file mode 100644 index 000000000..060af0850 --- /dev/null +++ b/integrations/issue-tracker/todoist-app/sync.ts @@ -0,0 +1,346 @@ +// @wc-ignore-file +/** + * One import pass: Todoist's active tasks into the app's `issue-v1` table, + * through ../todoist.ts for what each task becomes and for what happens to a + * task that stops appearing (#99). + * + * Reads first, all of them, then writes: a read that fails leaves the table + * as it was. Rows are matched by `todoist-task-id`. Todoist owns the + * imported columns: a task that changed there overwrites them, a local edit + * to one of them is overwritten at the next pass (#97's policy question; the + * read-only Moneybird app does the same), and nothing is ever sent to + * Todoist. No row is ever removed. + * + * A pass that finds nothing changed writes no row. `last-seen` would change + * on every pass if it were kept on every row, so it is not: an active task's + * last sighting is the App's `todoist-last-sync` (one write per complete + * read), and only a task no longer in the active list carries its own + * `todoist-last-seen`, as ../todoist.ts hands it over. + */ +import { createResolver } from '../../../ontology-kit/resolver.mjs'; +import { classes } from '../../../ontology-kit/terms.mjs'; +import type { JSONValue as AtomicJSON } from '../../../browser/lib/src/value.js'; +import type { + FetchedPlatform, + FetchedRecord, +} from '../../localthought/schema.js'; +import { + absentTodoistTasks, + reconcileTodoistTasks, + TODOIST_PLATFORM, + TODOIST_PRESENCE, + todoistFields, + type TodoistPresence, +} from '../todoist.js'; +import { + type Drive, + ISSUE_V1, + lastSync, + NAME, + PARENT, + recordSync, + TAG_DONE, + TAG_TODO, + TASK_BODY, + TASK_DUE_DATE, + TASK_STATUS, +} from './drive.js'; +import { + lookupTasks, + readActiveTasks, + readProjects, + type TodoistGet, + type TodoistResponse, +} from './read.js'; +import type { + HostProxy, + JSONValue, + PluginResource, + PluginStore, +} from './store.js'; + +export const PLATFORM = TODOIST_PLATFORM; + +/** Reads and writes `issue-v1` rows by property subject, strictly (#177 decision 1). */ +const resolver = createResolver({ classes: [classes['issue-v1']] }); + +export interface SyncSummary { + /** Task rows in the table after the pass. */ + total: number; + added: number; + updated: number; + unchanged: number; + /** Task rows by presence after the pass. */ + presence: Record; + /** Tasks back in the active list after being absent or settled. */ + reappeared: number; + /** How many absent tasks were looked up by id in this pass. */ + checked: number; + /** Whether the active-task read was complete (a partial read settles nothing). */ + complete: boolean; +} + +/** + * A `TodoistGet` over the host's proxy relay. The frame never holds a + * credential or calls the network itself; the host's frame client does. + */ +export function relayGet( + proxy: HostProxy, + connection: { platform: string; connectionId: string }, +): TodoistGet { + return async path => { + if (!path.startsWith('/api/v1/')) + throw new Error(`Refusing a Todoist path: ${path}`); + const response = await proxy.request({ + platform: connection.platform, + connectionId: connection.connectionId, + path, + method: 'GET', + }); + + return { status: response.status, body: response.body } as TodoistResponse; + }; +} + +const text = (value: unknown): string | undefined => + typeof value === 'string' && value ? value : undefined; + +/** Deep enough for the values written here: strings, booleans, string arrays. */ +const same = (a: JSONValue, b: JSONValue) => + Array.isArray(a) || Array.isArray(b) + ? JSON.stringify(a) === JSON.stringify(b) + : a === b; + +/** The task rows of the table as ../todoist.ts last returned them. */ +async function previousTasks( + store: PluginStore, + drive: Drive, + seenAt: string | undefined, +): Promise<{ previous: FetchedRecord[]; rows: Map }> { + const { taskId, source } = drive.properties; + const previous: FetchedRecord[] = []; + const rows = new Map(); + + for (const subject of await store.query({ + property: PARENT, + value: drive.table, + })) { + const row = await store.getResource(subject); + const id = text(row.get(taskId)); + // A row made in the table by hand has no Todoist task behind it: local + // only, left alone. A second row for the same task is left alone too. + if (!id || rows.has(id)) continue; + rows.set(id, row); + let values: Record = {}; + + try { + const parsed: unknown = JSON.parse(text(row.get(source)) ?? '{}'); + if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) + values = parsed as Record; + } catch { + // Unreadable source: the row is treated as an active task with no + // provider values, and the next read replaces them. + } + + const presence = values[todoistFields.presence]; + const active = + !TODOIST_PRESENCE.includes(presence as TodoistPresence) || + presence === 'active'; + if (active && seenAt && values[todoistFields.lastSeen] === undefined) + values = { ...values, [todoistFields.lastSeen]: seenAt }; + previous.push({ + resource: 'task', + namespace: PLATFORM, + id, + name: text(row.get(NAME)) ?? id, + values, + }); + } + + return { previous, rows }; +} + +/** What a row should hold for one reconciled task record. */ +function rowValues( + record: FetchedRecord, + drive: Drive, + projects: Map, +): { set: Record; unset: string[] } { + const p = drive.properties; + const v = record.values; + const presence = v[todoistFields.presence] as TodoistPresence; + const active = presence === 'active'; + const shared: Record = { + [NAME]: record.name, + [TASK_STATUS]: [v[todoistFields.done] === true ? TAG_DONE : TAG_TODO], + }; + const unset: string[] = []; + const body = text(v.description); + if (body) shared[TASK_BODY] = body; + else unset.push(TASK_BODY); + const due = text(v[todoistFields.dueDay]); + if (due) shared[TASK_DUE_DATE] = due; + else unset.push(TASK_DUE_DATE); + + const set = resolver.write(shared, ISSUE_V1) as Record; + set[p.taskId] = record.id; + set[p.presence] = presence; + + const optional: [string, string | undefined][] = [ + // An active task was seen at the App's last sync; see the header. + [p.lastSeen, active ? undefined : text(v[todoistFields.lastSeen])], + [p.priority, text(v[todoistFields.priorityLabel])], + [p.project, projects.get(text(v.project_id) ?? '')], + ]; + for (const [property, value] of optional) + if (value === undefined) unset.push(property); + else set[property] = value; + + const { [todoistFields.lastSeen]: seen, ...rest } = v; + set[p.source] = JSON.stringify( + active ? rest : { ...rest, [todoistFields.lastSeen]: seen }, + ); + + return { set, unset }; +} + +export interface SyncOptions { + /** The pass's time, stored exactly; tests pin it. */ + now?: () => string; + /** Page cap for the reads; tests force a partial read with it. */ + read?: { pageSize?: number; maxPages?: number }; +} + +/** + * Reads the projects, the complete active-task list and, for each previously + * imported task now missing from a complete list, that task by id; then + * reconciles (`reconcileTodoistTasks`) and writes what changed. + */ +export async function syncTasks( + store: PluginStore, + get: TodoistGet, + drive: Drive, + { now = () => new Date().toISOString(), read }: SyncOptions = {}, +): Promise { + const projects = await readProjects(get, read); + const fetched: FetchedPlatform = await readActiveTasks(get, read); + const { previous, rows } = await previousTasks( + store, + drive, + await lastSync(store, drive), + ); + const absent = absentTodoistTasks(previous, fetched); + const lookups = await lookupTasks(get, absent); + const seenAt = now(); + const { platform, summary } = reconcileTodoistTasks({ + previous, + fetched, + lookups, + seenAt, + }); + + const out: SyncSummary = { + total: 0, + added: 0, + updated: 0, + unchanged: 0, + presence: { + active: summary.active, + completed: summary.completed, + deleted: summary.deleted, + unavailable: summary.unavailable, + unconfirmed: summary.unconfirmed, + }, + reappeared: summary.reappeared, + checked: lookups.length, + complete: summary.complete, + }; + + for (const record of platform.records) { + if (record.resource !== 'task') continue; + out.total++; + const { set, unset } = rowValues(record, drive, projects); + const row = rows.get(record.id); + + if (!row) { + await store.newResource({ + parent: drive.table, + isA: [drive.rowClass], + propVals: set, + }); + out.added++; + continue; + } + + const changed = Object.entries(set).filter( + ([property, value]) => !same(row.get(property), value), + ); + const removed = unset.filter(property => row.get(property) !== undefined); + + if (!changed.length && !removed.length) { + out.unchanged++; + continue; + } + + for (const [property, value] of changed) row.set(property, value); + for (const property of removed) row.remove(property); + await row.save(); + out.updated++; + } + + // Rows are written first: a failed record of the read's time must not + // leave imported tasks unwritten, only this one timestamp stale. + if (summary.complete) await recordSync(store, drive, seenAt); + + return out; +} + +/** The table's task rows as the view lists them. Reads only. */ +export interface TaskRow { + subject: string; + taskId: string; + name: string; + done: boolean; + presence: string; + dueDay?: string; + priority?: string; + project?: string; + lastSeen?: string; +} + +export async function listTasks( + store: PluginStore, + drive: Drive, +): Promise { + const p = drive.properties; + const out: TaskRow[] = []; + + for (const subject of await store.query({ + property: PARENT, + value: drive.table, + })) { + const row = await store.getResource(subject); + const taskId = text(row.get(p.taskId)); + if (!taskId) continue; + const { values } = resolver.read(row.props, ISSUE_V1); + const status = values[TASK_STATUS]; + const optional = { + dueDay: text(values[TASK_DUE_DATE]), + priority: text(row.get(p.priority)), + project: text(row.get(p.project)), + lastSeen: text(row.get(p.lastSeen)), + }; + out.push({ + subject, + taskId, + name: text(values[NAME]) ?? taskId, + done: Array.isArray(status) && status.includes(TAG_DONE), + presence: text(row.get(p.presence)) ?? 'active', + ...Object.fromEntries( + Object.entries(optional).filter(([, v]) => v !== undefined), + ), + }); + } + + return out.sort((a, b) => a.name.localeCompare(b.name)); +} diff --git a/integrations/issue-tracker/todoist-app/tsconfig.json b/integrations/issue-tracker/todoist-app/tsconfig.json new file mode 100644 index 000000000..05cbfa6f1 --- /dev/null +++ b/integrations/issue-tracker/todoist-app/tsconfig.json @@ -0,0 +1,14 @@ +{ + // The Todoist drive app only; kept apart from ../tsconfig.json like + // ../app/tsconfig.json. `allowJs` for ontology-kit's .mjs modules (read, + // not checked; resolver.mjs has a .d.mts). Run through build.test.ts, or: + // browser/node_modules/.bin/tsc -p integrations/issue-tracker/todoist-app/tsconfig.json + "extends": "../tsconfig.json", + "compilerOptions": { + "allowJs": true, + "checkJs": false, + "lib": ["ES2023", "DOM"] + }, + "include": ["*.ts"], + "exclude": ["*.test.ts", "fakeStore.ts"] +} diff --git a/integrations/issue-tracker/todoist-fixture.test.ts b/integrations/issue-tracker/todoist-fixture.test.ts index 65073dede..8398f8496 100644 --- a/integrations/issue-tracker/todoist-fixture.test.ts +++ b/integrations/issue-tracker/todoist-fixture.test.ts @@ -1,12 +1,14 @@ // @wc-ignore-file /** - * Checks the recorded todoist mock-proxy fixture (fixtures/todoist/) against - * the adapter that consumes it, ./todoist.ts. Per PARALLEL_LANES.md §4 a - * recording that drops a field the adapter reads must fail here, not in e2e. + * Checks the todoist mock-proxy fixture (fixtures/todoist/) against the + * adapter that consumes it, ./todoist.ts. Per PARALLEL_LANES.md §4 a source + * that drops a field the adapter reads must fail here, not in e2e. * - * The api/-dependent tests skip until fixtures/todoist/record.mjs has been - * run against a live account (see its header for the command). Run with the - * AGENTS.md atomic-server layout: + * The fixture serves the recorded api/ when fixtures/todoist/record.mjs has + * been run against a live account (#46), and the SYNTHETIC rows of + * synthetic.mjs until then. Most checks run against either source; the + * recorded-only and synthetic-only ones say so. Run with the AGENTS.md + * atomic-server layout: * * browser/node_modules/.bin/vitest run \ * --config integrations/issue-tracker/vitest.config.ts todoist-fixture @@ -17,7 +19,12 @@ import { Datatype } from '../../browser/lib/src/index'; import type { JSONValue } from '../../browser/lib/src/value'; import { fixtures } from '../localthought/fixtures/index.mjs'; import { redactor } from './fixtures/todoist/record.mjs'; -import scenario, { recorded } from './fixtures/todoist/scenario.mjs'; +import scenario, { + recorded, + source, + todoistFixture, +} from './fixtures/todoist/scenario.mjs'; +import { SYNTHETIC } from './fixtures/todoist/synthetic.mjs'; import type { FetchedPlatform, FetchedRecord } from '../localthought/schema'; import { todoistFields as fields, todoistProjection } from './todoist'; @@ -29,6 +36,35 @@ type Page = { const isRecorded: boolean = recorded(); const DAY = /^\d{4}-\d{2}-\d{2}/; +const api = () => { + const fixture = todoistFixture(); + const get = (path: string, method = 'GET') => + fixture.request( + method, + new URL(`http://mock/proxy/todoist/api/v1${path}`), + ) as Page & { body: Row & { results: Row[] } }; + + return { fixture, get }; +}; + +/** Every row the fixture pages out for a collection, following cursors. */ +function paged( + get: ReturnType['get'], + collection: 'projects' | 'tasks', +): Row[] { + const seen: Row[] = []; + let res = get(`/${collection}?limit=3`); + + for (;;) { + expect(res.status).toBe(200); + seen.push(...res.body.results); + if (!res.body.next_cursor) break; + res = get(`/${collection}?cursor=${res.body.next_cursor}`); + } + + return seen; +} + describe('todoist fixture: always-on checks', () => { it('has the catalog document recorded from the real proxy', () => { const document = readFileSync(scenario.documentFile, 'utf8'); @@ -39,6 +75,18 @@ describe('todoist fixture: always-on checks', () => { expect(document).not.toMatch(/^ {4}(post|put|patch|delete):$/m); }); + it('is registered with the mock proxy, with its drivers', () => { + expect(fixtures.todoist).toBe(scenario); + expect(scenario.drivers).toEqual([ + 'completeTask', + 'reopenTask', + 'deleteTask', + 'removeTask', + 'failNext', + 'snapshot', + ]); + }); + it('redacts every string it does not know to be safe, consistently', () => { const redact = redactor(); const project: Row = redact.row('project', { @@ -90,25 +138,18 @@ describe('todoist fixture: always-on checks', () => { }); }); -describe.skipIf(!isRecorded)('todoist fixture: recorded api/', () => { - const pages = isRecorded - ? scenario.create().pages - : { projects: [], tasks: [] }; - const rows = (c: 'projects' | 'tasks'): Row[] => - (pages[c] as Page[]).flatMap(p => p.body.results); +describe(`todoist fixture: the ${isRecorded ? 'recorded' : 'synthetic'} source`, () => { + const rows = source(); - it('is registered with the mock proxy', () => { - expect(fixtures.todoist).toBe(scenario); - }); + it('has every field todoist.ts reads, with the type it expects', () => { + expect(rows.tasks.length).toBeGreaterThan(0); - it('records every field todoist.ts reads, with the type it expects', () => { - const tasks = rows('tasks'); - expect(tasks.length).toBeGreaterThan(0); - - for (const task of tasks) { + for (const task of rows.tasks as Row[]) { + expect(typeof task.id).toBe('string'); expect(typeof task.content).toBe('string'); expect(String(task.content).trim()).not.toBe(''); expect(typeof task.checked).toBe('boolean'); + expect(typeof task.description).toBe('string'); expect([1, 2, 3, 4]).toContain(task.priority); if (task.due !== null) { @@ -118,18 +159,14 @@ describe.skipIf(!isRecorded)('todoist fixture: recorded api/', () => { } } - expect(tasks.some(t => t.due !== null)).toBe(true); + expect(rows.tasks.some((t: Row) => t.due !== null)).toBe(true); + expect(rows.tasks.some((t: Row) => t.due === null)).toBe(true); }); - it('keeps ids redacted and project references intact', () => { - const projectIds = new Set(rows('projects').map(p => p.id)); - - for (const p of rows('projects')) expect(p.id).toMatch(/^project-\d+$/); - - for (const t of rows('tasks')) { - expect(t.id).toMatch(/^task-\d+$/); + it('keeps project references intact', () => { + const projectIds = new Set(rows.projects.map((p: Row) => p.id)); + for (const t of rows.tasks as Row[]) expect(projectIds).toContain(t.project_id); - } }); it('projects through todoistProjection', () => { @@ -160,8 +197,8 @@ describe.skipIf(!isRecorded)('todoist fixture: recorded api/', () => { terms: [term('task', 'class'), term('project', 'class')], }, records: [ - ...rows('tasks').map(r => record('task', r)), - ...rows('projects').map(r => record('project', r)), + ...(rows.tasks as Row[]).map(r => record('task', r)), + ...(rows.projects as Row[]).map(r => record('project', r)), ], }; const projected = todoistProjection(fetched).records.filter( @@ -178,31 +215,81 @@ describe.skipIf(!isRecorded)('todoist fixture: recorded api/', () => { }); it('replays pages by cursor, reads by id, and refuses writes', () => { - const api = scenario.create(); - const get = (path: string, method = 'GET') => - api.request(method, new URL(`http://mock/proxy/todoist/api/v1${path}`)); - - for (const collection of ['projects', 'tasks'] as const) { - const seen: Row[] = []; - let res = get(`/${collection}?limit=3`); - - for (;;) { - expect(res.status).toBe(200); - seen.push(...res.body.results); - if (!res.body.next_cursor) break; - res = get(`/${collection}?cursor=${res.body.next_cursor}`); - } + const { fixture, get } = api(); - expect(seen).toEqual(rows(collection)); - } + for (const collection of ['projects', 'tasks'] as const) + expect(paged(get, collection)).toEqual(rows[collection]); // At least one collection spans two pages, so cursor paging is exercised. + const pages = fixture.pages as Record; expect(pages.projects.length + pages.tasks.length).toBeGreaterThan(2); + expect(get('/tasks?cursor=page-99').status).toBe(400); - const task = rows('tasks')[0]; + const task = rows.tasks[0] as Row; expect(get(`/tasks/${task.id}`).body).toEqual(task); - expect(get('/tasks/task-0').status).toBe(404); + expect(get('/tasks/no-such-task').status).toBe(404); expect(get('/tasks', 'POST').status).toBe(403); expect(get('/access_tokens').status).toBe(404); }); + + it('shows the app what someone did in Todoist, and only by id once gone', () => { + const { fixture, get } = api(); + const [first, second, third] = rows.tasks as Row[]; + const ids = () => paged(get, 'tasks').map(t => t.id); + + fixture.completeTask(first.id as string); + expect(ids()).not.toContain(first.id); + expect(get(`/tasks/${first.id}`).body).toMatchObject({ + id: first.id, + checked: true, + }); + + fixture.deleteTask(second.id as string); + expect(ids()).not.toContain(second.id); + expect(get(`/tasks/${second.id}`).body).toMatchObject({ + is_deleted: true, + }); + + fixture.removeTask(third.id as string); + expect(ids()).not.toContain(third.id); + expect(get(`/tasks/${third.id}`).status).toBe(404); + + fixture.reopenTask(first.id as string); + expect(ids()).toContain(first.id); + expect(get(`/tasks/${first.id}`).body).toMatchObject({ checked: false }); + + expect(fixture.snapshot()).toMatchObject({ unreachable: [third.id] }); + + // Failures: the next matching request only. + fixture.failNext(1, 503, 'lookup'); + expect(get('/tasks').status).toBe(200); + expect(get(`/tasks/${first.id}`).status).toBe(503); + expect(get(`/tasks/${first.id}`).status).toBe(200); + fixture.failNext(1, 401); + expect(get('/projects').status).toBe(401); + expect(get('/projects').status).toBe(200); + expect(() => fixture.failNext(1, 503, 'sometimes')).toThrow(); + }); +}); + +describe.skipIf(isRecorded)('todoist fixture: synthetic only', () => { + it('says it is synthetic, in its flag and its ids', () => { + expect(SYNTHETIC).toBe(true); + const rows = source(); + expect(rows.synthetic).toBe(true); + for (const t of rows.tasks as Row[]) expect(t.id).toMatch(/^synthetic-/); + for (const p of rows.projects as Row[]) expect(p.id).toMatch(/^synthetic-/); + // Five tasks at three per page: two pages. + expect(rows.tasks).toHaveLength(5); + expect(rows.pageSize).toBe(3); + }); +}); + +describe.skipIf(!isRecorded)('todoist fixture: recorded only', () => { + it('keeps ids redacted', () => { + const rows = source(); + for (const p of rows.projects as Row[]) + expect(p.id).toMatch(/^project-\d+$/); + for (const t of rows.tasks as Row[]) expect(t.id).toMatch(/^task-\d+$/); + }); }); diff --git a/integrations/issue-tracker/vitest.config.ts b/integrations/issue-tracker/vitest.config.ts index 2bdf5c164..a83862aaf 100644 --- a/integrations/issue-tracker/vitest.config.ts +++ b/integrations/issue-tracker/vitest.config.ts @@ -48,6 +48,7 @@ export default { include: [ '*.test.ts', 'app/**/*.test.ts', + 'todoist-app/**/*.test.ts', 'devonian/**/*.test.{ts,mjs}', 'fixtures/**/*.test.ts', ], diff --git a/integrations/lanes.json b/integrations/lanes.json index 1470bce67..f6dbb0e90 100644 --- a/integrations/lanes.json +++ b/integrations/lanes.json @@ -68,8 +68,11 @@ "ontology/**", "ontology-kit/**" ], - "note": "paths: the app bundles ontology-kit/terms.mjs and resolver.mjs and its rows are of the shared issue-v1 class (#177 item 6), so an ontology change runs this lane too; the e2e reads issue-v1 from its published GitHub Pages subject (checked first with ontology-kit/served.mjs), so it needs network access to ontola.github.io. devonian/github-issues/ imports the devonian package from source (vitest.config.ts aliases it to devonian/src/main.ts), so a devonian change runs this lane too. Its tests ran in devonian CI before the lens moved here. The e2e installs the GitHub issues drive app (app/, npm devonian from app/package.json) from the catalog's Drive apps section, as the committed apps/issue-tracker//ui.js, and drives it through the host's proxy relay (atomic-server#1657, in the pin) against the mock proxy's seeded atomic-fixture/tracker repository.", - "e2e": ["integrations/issue-tracker/e2e/issue-tracker.spec.ts"] + "note": "paths: both apps bundle ontology-kit/terms.mjs and resolver.mjs and their rows are of the shared issue-v1 class (#177 item 6), so an ontology change runs this lane too; the e2es read issue-v1 from its published GitHub Pages subject (checked first with ontology-kit/served.mjs), so they need network access to ontola.github.io. devonian/github-issues/ imports the devonian package from source (vitest.config.ts aliases it to devonian/src/main.ts), so a devonian change runs this lane too. Its tests ran in devonian CI before the lens moved here. issue-tracker.spec.ts installs the GitHub issues drive app (app/, npm devonian from app/package.json) from the catalog's Drive apps section, as the committed apps/issue-tracker//ui.js, and drives it through the host's proxy relay (atomic-server#1657, in the pin) against the mock proxy's seeded atomic-fixture/tracker repository. todoist.spec.ts installs the read-only Todoist drive app (todoist-app/, #99's host journey) the same way, as apps/todoist//ui.js (apps.mjs APP_FOLDERS maps it there), against the SYNTHETIC todoist fixture in fixtures/todoist/ (hand-written from Todoist's API documentation; the recording is #46's), and uses its drivers to complete and hide tasks in Todoist.", + "e2e": [ + "integrations/issue-tracker/e2e/issue-tracker.spec.ts", + "integrations/issue-tracker/e2e/todoist.spec.ts" + ] }, { "id": "solid", diff --git a/integrations/localthought/README.md b/integrations/localthought/README.md index 80529d391..73ae8d712 100644 --- a/integrations/localthought/README.md +++ b/integrations/localthought/README.md @@ -203,9 +203,11 @@ deployment or live account writes have been performed as part of this work. ## Todoist tasks lens -The `devonian-todoist` catalog entry connects the proxy's `todoist` platform -through the same generic flow, with a read-only Devonian lens -(`../issue-tracker/todoist.ts`) on the way in. The proxy's Todoist catalog only grants +The `todoist` catalog entry used to connect the proxy's `todoist` platform +through the same generic flow (as `devonian-todoist`), with a read-only lens +(`../issue-tracker/todoist.ts`) on the way in; since that flow's removal the +lens's host is the Todoist drive app, `../issue-tracker/todoist-app/`, and +the entry installs that app. The proxy's Todoist catalog only grants `data:read`, so the lens has no write direction and the folder's Sync panel has no "preview edits" step: closing, editing or creating an issue locally is never sent to Todoist. diff --git a/integrations/localthought/fixtures/index.mjs b/integrations/localthought/fixtures/index.mjs index 9cdb7df56..466b10808 100644 --- a/integrations/localthought/fixtures/index.mjs +++ b/integrations/localthought/fixtures/index.mjs @@ -20,6 +20,8 @@ */ import googleCalendar from '../../calendar/fixtures/google-calendar/scenario.mjs'; import githubIssues from '../../issue-tracker/fixtures/github-issues/scenario.mjs'; +// Synthetic until #46 records api/: see issue-tracker/fixtures/todoist/synthetic.mjs. +import todoist from '../../issue-tracker/fixtures/todoist/scenario.mjs'; // Synthetic, not recorded: see money/fixtures/moneybird/synthetic.mjs. import moneybird from '../../money/fixtures/moneybird/scenario.mjs'; import notion from '../../notion/fixtures/notion/scenario.mjs'; @@ -33,14 +35,15 @@ export const fixtures = { moneybird, notion, pets, + todoist, }; /** * Parse a MOCK_PROXY_PLATFORMS value. Empty or unset means every fixture, so * callers that predate the variable (atomic-server's e2e-server.sh, dagger) * keep the full set. Requested platforms without a fixture are returned in - * `missing` rather than thrown: a lane may name a platform (todoist) - * whose fixture has not been recorded yet. + * `missing` rather than thrown: a lane may name a platform whose fixture + * does not exist yet. */ export function selectPlatforms(value) { const requested = [ diff --git a/integrations/localthought/mock-proxy.test.mjs b/integrations/localthought/mock-proxy.test.mjs index fc70d94f5..5c9477525 100644 --- a/integrations/localthought/mock-proxy.test.mjs +++ b/integrations/localthought/mock-proxy.test.mjs @@ -305,6 +305,7 @@ test('connect: consent without login, signed redeem makes the owner, delegation, 'moneybird', 'notion', 'pets', + 'todoist', ]); // The retired flow's parameters, a foreign return address, an unknown @@ -736,7 +737,7 @@ test('MOCK_PROXY_PLATFORMS restricts the catalog, consent and catalog documents' const warn = console.warn; const warnings = []; console.warn = message => warnings.push(message); - const server = mockProxy({ platforms: 'pets,todoist,pets' }); + const server = mockProxy({ platforms: 'pets,nonesuch,pets' }); console.warn = warn; await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); const base = `http://127.0.0.1:${server.address().port}`; @@ -744,7 +745,7 @@ test('MOCK_PROXY_PLATFORMS restricts the catalog, consent and catalog documents' try { assert.deepEqual(await (await fetch(`${base}/catalog`)).json(), ['pets']); assert.deepEqual(warnings, [ - 'mock-proxy: no fixture for todoist; not served', + 'mock-proxy: no fixture for nonesuch; not served', ]); assert.equal((await fetch(`${base}/catalog/pets.yaml`)).status, 200); assert.equal((await fetch(`${base}/catalog/clockify.yaml`)).status, 404); @@ -770,6 +771,7 @@ test('an empty platform list serves every fixture', async () => { 'moneybird', 'notion', 'pets', + 'todoist', ]) assert.equal((await fetch(`${base}/catalog/${id}.yaml`)).status, 200); assert.ok(server.github.createIssue); diff --git a/integrations/tooling/apps.mjs b/integrations/tooling/apps.mjs index 12f8565e9..e029f1dc3 100644 --- a/integrations/tooling/apps.mjs +++ b/integrations/tooling/apps.mjs @@ -92,10 +92,12 @@ export function appEntries(catalog) { * `build.mjs` and a `private` `package.json` with just its version. For an * app that lives inside another plugin's folder, such as Moneybird inside * `integrations/money/` beside the Bank statements importer, whose own - * package.json version belongs to that importer. + * package.json version belongs to that importer, or the Todoist app inside + * `integrations/issue-tracker/` beside the GitHub issues app at `app/`. */ export const APP_FOLDERS = Object.freeze({ moneybird: 'integrations/money/moneybird', + todoist: 'integrations/issue-tracker/todoist-app', }); /** The repository-relative folder holding an app's `build.mjs`. */ diff --git a/integrations/tooling/apps.test.mjs b/integrations/tooling/apps.test.mjs index c0d23c083..b5d8f5c02 100644 --- a/integrations/tooling/apps.test.mjs +++ b/integrations/tooling/apps.test.mjs @@ -183,6 +183,7 @@ test('an app-only folder records its version in app/package.json', () => test('an app resolves to integrations//app/ unless APP_FOLDERS maps it', () => { assert.equal(appFolder('gamma'), 'integrations/gamma/app'); assert.equal(appFolder('moneybird'), 'integrations/money/moneybird'); + assert.equal(appFolder('todoist'), 'integrations/issue-tracker/todoist-app'); // Only own keys map: no prototype property is taken for a folder. assert.equal(appFolder('constructor'), 'integrations/constructor/app'); assert.ok(Object.isFrozen(APP_FOLDERS));