@withpica/mcp-server 2.6.2 → 2.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/dist/pica-sdk.d.ts +1231 -0
  2. package/dist/pica-sdk.d.ts.map +1 -0
  3. package/dist/pica-sdk.js +1403 -0
  4. package/dist/pica-sdk.js.map +1 -0
  5. package/dist/tools/assets.d.ts +4 -0
  6. package/dist/tools/assets.d.ts.map +1 -1
  7. package/dist/tools/assets.js +190 -0
  8. package/dist/tools/assets.js.map +1 -1
  9. package/dist/tools/audio-files.d.ts.map +1 -1
  10. package/dist/tools/audio-files.js +5 -5
  11. package/dist/tools/audio-files.js.map +1 -1
  12. package/dist/tools/collaborators.d.ts +4 -0
  13. package/dist/tools/collaborators.d.ts.map +1 -1
  14. package/dist/tools/collaborators.js +188 -8
  15. package/dist/tools/collaborators.js.map +1 -1
  16. package/dist/tools/custody-hints.d.ts +16 -0
  17. package/dist/tools/custody-hints.d.ts.map +1 -0
  18. package/dist/tools/custody-hints.js +27 -0
  19. package/dist/tools/custody-hints.js.map +1 -0
  20. package/dist/tools/custody.d.ts +38 -0
  21. package/dist/tools/custody.d.ts.map +1 -0
  22. package/dist/tools/custody.js +274 -0
  23. package/dist/tools/custody.js.map +1 -0
  24. package/dist/tools/enrichment.d.ts.map +1 -1
  25. package/dist/tools/enrichment.js +6 -6
  26. package/dist/tools/enrichment.js.map +1 -1
  27. package/dist/tools/exports.d.ts.map +1 -1
  28. package/dist/tools/exports.js +4 -4
  29. package/dist/tools/exports.js.map +1 -1
  30. package/dist/tools/index.d.ts.map +1 -1
  31. package/dist/tools/index.js +6 -0
  32. package/dist/tools/index.js.map +1 -1
  33. package/dist/tools/metadata.d.ts.map +1 -1
  34. package/dist/tools/metadata.js +37 -0
  35. package/dist/tools/metadata.js.map +1 -1
  36. package/dist/tools/notifications.d.ts +3 -0
  37. package/dist/tools/notifications.d.ts.map +1 -1
  38. package/dist/tools/notifications.js +176 -27
  39. package/dist/tools/notifications.js.map +1 -1
  40. package/dist/tools/recordings.d.ts.map +1 -1
  41. package/dist/tools/recordings.js +16 -1
  42. package/dist/tools/recordings.js.map +1 -1
  43. package/dist/tools/telegram.d.ts +1 -0
  44. package/dist/tools/telegram.d.ts.map +1 -1
  45. package/dist/tools/telegram.js +53 -0
  46. package/dist/tools/telegram.js.map +1 -1
  47. package/dist/tools/works.d.ts.map +1 -1
  48. package/dist/tools/works.js +15 -0
  49. package/dist/tools/works.js.map +1 -1
  50. package/dist/utils/errors.d.ts +29 -0
  51. package/dist/utils/errors.d.ts.map +1 -0
  52. package/dist/utils/errors.js +115 -0
  53. package/dist/utils/errors.js.map +1 -0
  54. package/dist/utils/formatting.d.ts +82 -0
  55. package/dist/utils/formatting.d.ts.map +1 -0
  56. package/dist/utils/formatting.js +125 -0
  57. package/dist/utils/formatting.js.map +1 -0
  58. package/package.json +1 -1
  59. package/server.json +1 -1
@@ -1,5 +1,5 @@
1
1
  // Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
2
- import { formatSuccess, formatList, } from "@withpica/mcp-utils";
2
+ import { formatSuccess, formatList } from "@withpica/mcp-utils";
3
3
  export class CollaboratorsTools {
4
4
  pica;
5
5
  constructor(pica) {
@@ -51,14 +51,21 @@ export class CollaboratorsTools {
51
51
  {
52
52
  definition: {
53
53
  name: "pica_collaborators_invites_list",
54
- description: "List collaboration invites with optional filters. Returns pending, accepted, or expired invites.",
54
+ description: "Sender-side: list collaboration invites this organisation has sent. Filter by status (pending / verified / confirmed / expired / cancelled / disputed) or by work. For the recipient-side equivalent see pica_collaborators_incoming_list.",
55
55
  inputSchema: {
56
56
  type: "object",
57
57
  properties: {
58
58
  status: {
59
59
  type: "string",
60
60
  description: "Filter by status (default: 'pending')",
61
- enum: ["pending", "accepted", "expired"],
61
+ enum: [
62
+ "pending",
63
+ "verified",
64
+ "confirmed",
65
+ "expired",
66
+ "cancelled",
67
+ "disputed",
68
+ ],
62
69
  },
63
70
  work_id: {
64
71
  type: "string",
@@ -73,6 +80,108 @@ export class CollaboratorsTools {
73
80
  },
74
81
  executor: this.listInvites.bind(this),
75
82
  },
83
+ {
84
+ definition: {
85
+ name: "pica_collaborators_incoming_list",
86
+ description: "ADR-157 warm path. List collaboration invites addressed to YOUR email across every inviting org. Returns pending invites by default — pass status to see disputed/confirmed history. Each row includes work_title, inviter_org_name, credit_type, and percentage_split so you can decide whether to accept.",
87
+ inputSchema: {
88
+ type: "object",
89
+ properties: {
90
+ status: {
91
+ type: "string",
92
+ description: "Filter by status (default: 'pending')",
93
+ enum: [
94
+ "pending",
95
+ "verified",
96
+ "confirmed",
97
+ "expired",
98
+ "cancelled",
99
+ "disputed",
100
+ ],
101
+ },
102
+ limit: {
103
+ type: "number",
104
+ description: "Maximum results to return (default: 50, max: 100)",
105
+ },
106
+ },
107
+ },
108
+ },
109
+ executor: this.listIncoming.bind(this),
110
+ },
111
+ {
112
+ definition: {
113
+ name: "pica_collaborators_accept",
114
+ description: "ADR-157 warm path. Accept a collaboration invite addressed to your email. Writes a real work_credits row on the inviter's work and notifies them. Fails if the invite is not addressed to your authenticated email. Use pica_collaborators_incoming_list to find the invite_id first.",
115
+ inputSchema: {
116
+ type: "object",
117
+ properties: {
118
+ invite_id: {
119
+ type: "string",
120
+ description: "The invite id to accept",
121
+ },
122
+ },
123
+ required: ["invite_id"],
124
+ },
125
+ },
126
+ executor: this.acceptInvite.bind(this),
127
+ },
128
+ {
129
+ definition: {
130
+ name: "pica_collaborators_dispute",
131
+ description: 'ADR-157 warm path. Dispute a collaboration invite addressed to your email ("that\'s not me" or "I wasn\'t on this work"). Flips the invite to disputed and notifies the inviter. Does NOT create any credits.',
132
+ inputSchema: {
133
+ type: "object",
134
+ properties: {
135
+ invite_id: {
136
+ type: "string",
137
+ description: "The invite id to dispute",
138
+ },
139
+ reason: {
140
+ type: "string",
141
+ description: "Optional freeform reason for the dispute",
142
+ },
143
+ },
144
+ required: ["invite_id"],
145
+ },
146
+ },
147
+ executor: this.disputeInvite.bind(this),
148
+ },
149
+ {
150
+ definition: {
151
+ name: "pica_collaborators_invite_bulk",
152
+ description: "ADR-157 warm path. Send multiple collaboration invites in one call. Thin wrapper over pica_collaborators_invite — same per-row schema, returns per-row { ok, email, invite?, error? } so partial failures are visible.",
153
+ inputSchema: {
154
+ type: "object",
155
+ properties: {
156
+ invites: {
157
+ type: "array",
158
+ description: "Array of invites to send",
159
+ items: {
160
+ type: "object",
161
+ properties: {
162
+ work_id: { type: "string" },
163
+ name: { type: "string" },
164
+ email: { type: "string" },
165
+ role: { type: "string" },
166
+ invited_by: { type: "string" },
167
+ credit_type: { type: "string" },
168
+ percentage_split: { type: "number" },
169
+ },
170
+ required: [
171
+ "work_id",
172
+ "name",
173
+ "email",
174
+ "invited_by",
175
+ "credit_type",
176
+ ],
177
+ },
178
+ },
179
+ },
180
+ required: ["invites"],
181
+ },
182
+ },
183
+ executor: this.inviteBulk.bind(this),
184
+ },
76
185
  {
77
186
  definition: {
78
187
  name: "pica_collaborators_invite_resend",
@@ -116,16 +225,87 @@ export class CollaboratorsTools {
116
225
  return formatSuccess(`Invite sent to ${args.name} (${args.email}) for credit "${args.credit_type}" on work ${args.work_id}.`, result, hints);
117
226
  }
118
227
  async listInvites(args) {
119
- const invites = await this.pica.collaborators.listInvites({
120
- status: args.status,
121
- workId: args.work_id,
122
- limit: args.limit,
228
+ // ADR-157 sub-step 4b (superseded form): the original plan surfaced
229
+ // an "events since last review" watermark hint, but sub-step 4a
230
+ // already delivers confirmed/disputed receipts instantly via
231
+ // Telegram — making the duplicated completion-hint surface
232
+ // redundant. ADR-160 reinforces the receipts-layer principle. All
233
+ // that remains is nudging unpaired orgs towards Telegram, via a
234
+ // single parallel call to the existing telegram status endpoint.
235
+ // Status-check failure degrades to "no nudge" so the primary read
236
+ // path stays resilient.
237
+ const [invites, telegramStatus] = await Promise.all([
238
+ this.pica.collaborators.listInvites({
239
+ status: args.status,
240
+ workId: args.work_id,
241
+ limit: args.limit,
242
+ }),
243
+ this.pica.telegram.getStatus().catch(() => null),
244
+ ]);
245
+ const hints = [];
246
+ if (telegramStatus && telegramStatus.connected === false) {
247
+ hints.push({
248
+ gap: "telegram_not_connected",
249
+ suggestion: "Want collaborator accept/dispute receipts delivered instantly? Pair Telegram with pica_telegram_connect — the message body is the receipt, no dashboard trip.",
250
+ severity: "nice_to_have",
251
+ });
252
+ }
253
+ return formatList(invites, {
254
+ status: args.status || "pending",
255
+ completion_hints: hints,
123
256
  });
124
- return formatList(invites, { status: args.status || "pending" });
125
257
  }
126
258
  async resendInvite(args) {
127
259
  const result = await this.pica.collaborators.resendInvite(args.invite_id);
128
260
  return formatSuccess(`Invite ${args.invite_id} resent successfully.`, result);
129
261
  }
262
+ async listIncoming(args) {
263
+ const invites = await this.pica.collaborators.listIncoming({
264
+ status: args.status,
265
+ limit: args.limit,
266
+ });
267
+ const hints = [];
268
+ if (invites.length > 0) {
269
+ hints.push({
270
+ gap: "pending_incoming_invites",
271
+ suggestion: `You have ${invites.length} pending invite${invites.length === 1 ? "" : "s"}. Accept with pica_collaborators_accept or reject with pica_collaborators_dispute.`,
272
+ severity: "important",
273
+ });
274
+ }
275
+ return formatList(invites, {
276
+ status: args.status || "pending",
277
+ count: invites.length,
278
+ completion_hints: hints,
279
+ });
280
+ }
281
+ async acceptInvite(args) {
282
+ const result = await this.pica.collaborators.accept(args.invite_id);
283
+ const hints = [
284
+ {
285
+ gap: "credit_attested",
286
+ suggestion: "Your credit is now live on the inviter's work. Use pica_works_query to see works you're credited on.",
287
+ severity: "nice_to_have",
288
+ },
289
+ ];
290
+ return formatSuccess(`Invite ${args.invite_id} accepted. Credit written.`, result, hints);
291
+ }
292
+ async disputeInvite(args) {
293
+ const result = await this.pica.collaborators.dispute(args.invite_id, args.reason);
294
+ return formatSuccess(`Invite ${args.invite_id} disputed. The inviter has been notified.`, result);
295
+ }
296
+ async inviteBulk(args) {
297
+ const results = await this.pica.collaborators.inviteBulk(args.invites.map((i) => ({
298
+ workId: i.work_id,
299
+ personData: { name: i.name, email: i.email, role: i.role },
300
+ invitedBy: i.invited_by,
301
+ creditData: {
302
+ credit_type: i.credit_type,
303
+ percentage_split: i.percentage_split,
304
+ },
305
+ })));
306
+ const okCount = results.filter((r) => r.ok).length;
307
+ const failCount = results.length - okCount;
308
+ return formatSuccess(`Bulk invite complete: ${okCount} sent, ${failCount} failed.`, { results, ok: okCount, failed: failCount });
309
+ }
130
310
  }
131
311
  //# sourceMappingURL=collaborators.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"collaborators.js","sourceRoot":"","sources":["../../src/tools/collaborators.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"collaborators.js","sourceRoot":"","sources":["../../src/tools/collaborators.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAqB7D,OAAO,EAAE,aAAa,EAAE,UAAU,EAAkB,MAAM,qBAAqB,CAAC;AAEhF,MAAM,OAAO,kBAAkB;IACrB,IAAI,CAAa;IAEzB,YAAY,IAAgB;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,QAAQ;QACN,OAAO;YACL;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,2BAA2B;oBACjC,WAAW,EACT,kPAAkP;oBACpP,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,OAAO,EAAE;gCACP,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,2CAA2C;6BACzD;4BACD,IAAI,EAAE;gCACJ,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,+BAA+B;6BAC7C;4BACD,KAAK,EAAE;gCACL,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,mCAAmC;6BACjD;4BACD,IAAI,EAAE;gCACJ,IAAI,EAAE,QAAQ;gCACd,WAAW,EACT,yEAAyE;6BAC5E;4BACD,UAAU,EAAE;gCACV,IAAI,EAAE,QAAQ;gCACd,WAAW,EACT,wGAAwG;6BAC3G;4BACD,WAAW,EAAE;gCACX,IAAI,EAAE,QAAQ;gCACd,WAAW,EACT,gFAAgF;6BACnF;4BACD,gBAAgB,EAAE;gCAChB,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,0CAA0C;6BACxD;yBACF;wBACD,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,CAAC;qBACpE;iBACF;gBACD,QAAQ,EAAE,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC;aAC7C;YACD;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,iCAAiC;oBACvC,WAAW,EACT,4OAA4O;oBAC9O,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,MAAM,EAAE;gCACN,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,uCAAuC;gCACpD,IAAI,EAAE;oCACJ,SAAS;oCACT,UAAU;oCACV,WAAW;oCACX,SAAS;oCACT,WAAW;oCACX,UAAU;iCACX;6BACF;4BACD,OAAO,EAAE;gCACP,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,oCAAoC;6BAClD;4BACD,KAAK,EAAE;gCACL,IAAI,EAAE,QAAQ;gCACd,WAAW,EACT,mDAAmD;6BACtD;yBACF;qBACF;iBACF;gBACD,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;aACtC;YACD;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,kCAAkC;oBACxC,WAAW,EACT,6SAA6S;oBAC/S,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,MAAM,EAAE;gCACN,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,uCAAuC;gCACpD,IAAI,EAAE;oCACJ,SAAS;oCACT,UAAU;oCACV,WAAW;oCACX,SAAS;oCACT,WAAW;oCACX,UAAU;iCACX;6BACF;4BACD,KAAK,EAAE;gCACL,IAAI,EAAE,QAAQ;gCACd,WAAW,EACT,mDAAmD;6BACtD;yBACF;qBACF;iBACF;gBACD,QAAQ,EAAE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;aACvC;YACD;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,2BAA2B;oBACjC,WAAW,EACT,uRAAuR;oBACzR,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,SAAS,EAAE;gCACT,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,yBAAyB;6BACvC;yBACF;wBACD,QAAQ,EAAE,CAAC,WAAW,CAAC;qBACxB;iBACF;gBACD,QAAQ,EAAE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;aACvC;YACD;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,4BAA4B;oBAClC,WAAW,EACT,+MAA+M;oBACjN,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,SAAS,EAAE;gCACT,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,0BAA0B;6BACxC;4BACD,MAAM,EAAE;gCACN,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,0CAA0C;6BACxD;yBACF;wBACD,QAAQ,EAAE,CAAC,WAAW,CAAC;qBACxB;iBACF;gBACD,QAAQ,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;aACxC;YACD;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,gCAAgC;oBACtC,WAAW,EACT,wNAAwN;oBAC1N,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,OAAO,EAAE;gCACP,IAAI,EAAE,OAAO;gCACb,WAAW,EAAE,0BAA0B;gCACvC,KAAK,EAAE;oCACL,IAAI,EAAE,QAAQ;oCACd,UAAU,EAAE;wCACV,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wCAC3B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wCACxB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wCACzB,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wCACxB,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wCAC9B,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wCAC/B,gBAAgB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;qCACrC;oCACD,QAAQ,EAAE;wCACR,SAAS;wCACT,MAAM;wCACN,OAAO;wCACP,YAAY;wCACZ,aAAa;qCACd;iCACF;6BACF;yBACF;wBACD,QAAQ,EAAE,CAAC,SAAS,CAAC;qBACtB;iBACF;gBACD,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;aACrC;YACD;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,kCAAkC;oBACxC,WAAW,EACT,4FAA4F;oBAC9F,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,SAAS,EAAE;gCACT,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,yBAAyB;6BACvC;yBACF;wBACD,QAAQ,EAAE,CAAC,WAAW,CAAC;qBACxB;iBACF;gBACD,QAAQ,EAAE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;aACvC;SACF,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,kBAAkB,CAC9B,IAAyB;QAEzB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC;YAClD,MAAM,EAAE,IAAI,CAAC,OAAO;YACpB,UAAU,EAAE;gBACV,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,IAAI,EAAE,IAAI,CAAC,IAAI;aAChB;YACD,SAAS,EAAE,IAAI,CAAC,UAAU;YAC1B,UAAU,EAAE;gBACV,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;aACxC;SACF,CAAC,CAAC;QAEH,MAAM,KAAK,GAAqB;YAC9B;gBACE,GAAG,EAAE,kCAAkC;gBACvC,UAAU,EAAE,UAAU,IAAI,CAAC,IAAI,oEAAoE;gBACnG,QAAQ,EAAE,WAAW;aACtB;SACF,CAAC;QAEF,OAAO,aAAa,CAClB,kBAAkB,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,KAAK,iBAAiB,IAAI,CAAC,WAAW,aAAa,IAAI,CAAC,OAAO,GAAG,EACvG,MAAM,EACN,KAAK,CACN,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,IAAyB;QACjD,oEAAoE;QACpE,gEAAgE;QAChE,6DAA6D;QAC7D,2DAA2D;QAC3D,kEAAkE;QAClE,gEAAgE;QAChE,iEAAiE;QACjE,kEAAkE;QAClE,wBAAwB;QACxB,MAAM,CAAC,OAAO,EAAE,cAAc,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAClD,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC;gBAClC,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,MAAM,EAAE,IAAI,CAAC,OAAO;gBACpB,KAAK,EAAE,IAAI,CAAC,KAAK;aAClB,CAAC;YACF,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;SACjD,CAAC,CAAC;QAEH,MAAM,KAAK,GAAqB,EAAE,CAAC;QACnC,IAAI,cAAc,IAAI,cAAc,CAAC,SAAS,KAAK,KAAK,EAAE,CAAC;YACzD,KAAK,CAAC,IAAI,CAAC;gBACT,GAAG,EAAE,wBAAwB;gBAC7B,UAAU,EACR,+JAA+J;gBACjK,QAAQ,EAAE,cAAc;aACzB,CAAC,CAAC;QACL,CAAC;QAED,OAAO,UAAU,CAAC,OAAO,EAAE;YACzB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,SAAS;YAChC,gBAAgB,EAAE,KAAK;SACxB,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,IAAyB;QAClD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC1E,OAAO,aAAa,CAClB,UAAU,IAAI,CAAC,SAAS,uBAAuB,EAC/C,MAAM,CACP,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,IAAyB;QAClD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC;YACzD,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC,CAAC;QACH,MAAM,KAAK,GAAqB,EAAE,CAAC;QACnC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,KAAK,CAAC,IAAI,CAAC;gBACT,GAAG,EAAE,0BAA0B;gBAC/B,UAAU,EAAE,YAAY,OAAO,CAAC,MAAM,kBAAkB,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,oFAAoF;gBAC3K,QAAQ,EAAE,WAAW;aACtB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,UAAU,CAAC,OAAO,EAAE;YACzB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,SAAS;YAChC,KAAK,EAAE,OAAO,CAAC,MAAM;YACrB,gBAAgB,EAAE,KAAK;SACxB,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,IAAyB;QAClD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACpE,MAAM,KAAK,GAAqB;YAC9B;gBACE,GAAG,EAAE,iBAAiB;gBACtB,UAAU,EACR,sGAAsG;gBACxG,QAAQ,EAAE,cAAc;aACzB;SACF,CAAC;QACF,OAAO,aAAa,CAClB,UAAU,IAAI,CAAC,SAAS,4BAA4B,EACpD,MAAM,EACN,KAAK,CACN,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,aAAa,CAAC,IAAyB;QACnD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,CAClD,IAAI,CAAC,SAAS,EACd,IAAI,CAAC,MAAM,CACZ,CAAC;QACF,OAAO,aAAa,CAClB,UAAU,IAAI,CAAC,SAAS,2CAA2C,EACnE,MAAM,CACP,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,UAAU,CAAC,IAAyB;QAChD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,UAAU,CACrD,IAAI,CAAC,OAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAClC,MAAM,EAAE,CAAC,CAAC,OAAO;YACjB,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;YAC1D,SAAS,EAAE,CAAC,CAAC,UAAU;YACvB,UAAU,EAAE;gBACV,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,gBAAgB,EAAE,CAAC,CAAC,gBAAgB;aACrC;SACF,CAAC,CAAC,CACJ,CAAC;QACF,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC;QACxD,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC;QAC3C,OAAO,aAAa,CAClB,yBAAyB,OAAO,UAAU,SAAS,UAAU,EAC7D,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAC5C,CAAC;IACJ,CAAC;CACF"}
@@ -0,0 +1,16 @@
1
+ /**
2
+ * ADR-158 Plan C Phase 2 — completion hints for pica_works_create.
3
+ *
4
+ * When a fresh work is created, the custody columns default to
5
+ * "entry_default" (the org that typed it in is the placeholder custodian
6
+ * until an actual claim is made). These hints nudge the agent to have
7
+ * the rights conversation immediately rather than leaving custody dangling.
8
+ *
9
+ * The helper is intentionally defensive — the SDK's `Work` TS interface
10
+ * does not declare `composition_custody_source` / `master_custody_source`,
11
+ * but the API returns them as JSON pass-through from `worksService.create`.
12
+ * Callers pass the raw work object; we read the fields with a typed wrapper.
13
+ */
14
+ import type { CompletionHint } from "@withpica/mcp-utils";
15
+ export declare function buildCustodyHints(work: unknown): CompletionHint[];
16
+ //# sourceMappingURL=custody-hints.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"custody-hints.d.ts","sourceRoot":"","sources":["../../src/tools/custody-hints.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAO1D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,EAAE,CA+BjE"}
@@ -0,0 +1,27 @@
1
+ // Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
2
+ export function buildCustodyHints(work) {
3
+ const w = (work ?? {});
4
+ const hints = [];
5
+ if (w.composition_custody_source === "entry_default") {
6
+ hints.push({
7
+ gap: "custody_unclaimed_composition",
8
+ severity: "important",
9
+ suggestion: "Who holds the publishing (composition) rights? If you, call pica_custody_claim with chain='composition'. If someone else (publisher, co-writer), invite them via pica_collaborators_invite and let them claim custody on acceptance.",
10
+ });
11
+ }
12
+ if (w.master_custody_source === "entry_default") {
13
+ hints.push({
14
+ gap: "custody_unclaimed_master",
15
+ severity: "important",
16
+ suggestion: "Who holds the recording (master) rights? Label, distributor, self-released? Same pattern — claim it yourself via pica_custody_claim with chain='master', or invite the rightsholder.",
17
+ });
18
+ }
19
+ // Always fire the split hint — we never know splits from a single work row.
20
+ hints.push({
21
+ gap: "rights_share_unknown",
22
+ severity: "nice_to_have",
23
+ suggestion: "Is the publishing 100% yours or split with co-writers? If split, add co-writers via pica_work_credits_add with their percentage shares so the splits sum to 100. Then invite them via pica_collaborators_invite to confirm.",
24
+ });
25
+ return hints;
26
+ }
27
+ //# sourceMappingURL=custody-hints.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"custody-hints.js","sourceRoot":"","sources":["../../src/tools/custody-hints.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAuB7D,MAAM,UAAU,iBAAiB,CAAC,IAAa;IAC7C,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAoB,CAAC;IAC1C,MAAM,KAAK,GAAqB,EAAE,CAAC;IAEnC,IAAI,CAAC,CAAC,0BAA0B,KAAK,eAAe,EAAE,CAAC;QACrD,KAAK,CAAC,IAAI,CAAC;YACT,GAAG,EAAE,+BAA+B;YACpC,QAAQ,EAAE,WAAW;YACrB,UAAU,EACR,sOAAsO;SACzO,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC,CAAC,qBAAqB,KAAK,eAAe,EAAE,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC;YACT,GAAG,EAAE,0BAA0B;YAC/B,QAAQ,EAAE,WAAW;YACrB,UAAU,EACR,sLAAsL;SACzL,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,IAAI,CAAC;QACT,GAAG,EAAE,sBAAsB;QAC3B,QAAQ,EAAE,cAAc;QACxB,UAAU,EACR,6NAA6N;KAChO,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC;AACf,CAAC"}
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Custody MCP Tools — ADR-158 Plan C Phase 1
3
+ *
4
+ * Six tools covering the custody claim lifecycle + reconciliation, exposed
5
+ * on the stdio transport. Thin wrappers around this.pica.custody.* which
6
+ * calls the HTTP routes under /api/admin/custody/.
7
+ *
8
+ * Tools:
9
+ * pica_custody_claim — request custody of a work's chain
10
+ * pica_custody_respond — accept/decline/dispute an incoming claim
11
+ * pica_custody_list — list incoming + outgoing claims
12
+ * pica_custody_history — custody-related provenance_history rows
13
+ * pica_custody_resolve_pending — preview inheritable works for a global_publisher_id
14
+ * pica_custody_reconcile — bulk-claim inheritable works
15
+ *
16
+ * RBAC (enforced at the HTTP route layer, see app/api/admin/custody/*):
17
+ * claim, respond, resolve_pending, reconcile → admin/owner only
18
+ * list, history → any authenticated member
19
+ *
20
+ * Pricing: FREE. ADR-162 deprecates credit gating as a user-facing concept.
21
+ */
22
+ import { PicaClient } from "@withpica/mcp-sdk";
23
+ import type { ToolDefinition, ToolExecutor } from "./index.js";
24
+ export declare class CustodyTools {
25
+ private pica;
26
+ constructor(pica: PicaClient);
27
+ getTools(): Array<{
28
+ definition: ToolDefinition;
29
+ executor: ToolExecutor;
30
+ }>;
31
+ private claim;
32
+ private respond;
33
+ private list;
34
+ private history;
35
+ private resolvePending;
36
+ private reconcile;
37
+ }
38
+ //# sourceMappingURL=custody.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"custody.d.ts","sourceRoot":"","sources":["../../src/tools/custody.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAG3E,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YAwM3D,KAAK;YAYL,OAAO;YAeP,IAAI;YA0BJ,OAAO;YAeP,cAAc;YAuBd,SAAS;CAgBxB"}
@@ -0,0 +1,274 @@
1
+ // Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
2
+ import { formatSuccess } from "@withpica/mcp-utils";
3
+ export class CustodyTools {
4
+ pica;
5
+ constructor(pica) {
6
+ this.pica = pica;
7
+ }
8
+ getTools() {
9
+ return [
10
+ {
11
+ definition: {
12
+ name: "pica_custody_claim",
13
+ description: "Request custody of a work's composition or master chain. " +
14
+ "If another org currently holds custody, creates a pending claim; the current " +
15
+ "custodian has 7 days to accept, decline, or dispute before the claim auto-approves. " +
16
+ "If you already hold custody, this errors. Admin/owner access required.",
17
+ inputSchema: {
18
+ type: "object",
19
+ properties: {
20
+ work_id: {
21
+ type: "string",
22
+ description: "UUID of the work to claim.",
23
+ },
24
+ chain: {
25
+ type: "string",
26
+ enum: ["composition", "master"],
27
+ description: "'composition' = publishing rights; 'master' = recording rights.",
28
+ },
29
+ reason: {
30
+ type: "string",
31
+ description: "Optional freetext shown to the current custodian in the notification.",
32
+ },
33
+ },
34
+ required: ["work_id", "chain"],
35
+ },
36
+ annotations: {
37
+ title: "claim custody",
38
+ destructiveHint: false,
39
+ idempotentHint: false,
40
+ },
41
+ },
42
+ executor: this.claim.bind(this),
43
+ },
44
+ {
45
+ definition: {
46
+ name: "pica_custody_respond",
47
+ description: "Respond to an incoming custody claim. Actions: 'accept' transfers custody " +
48
+ "to the claimant; 'decline' rejects the claim (custody unchanged); 'dispute' " +
49
+ "freezes the claim for human review. reason is required for dispute. Only the " +
50
+ "current custodian can accept or decline; the custodian OR any credited party " +
51
+ "can dispute. Admin/owner access required.",
52
+ inputSchema: {
53
+ type: "object",
54
+ properties: {
55
+ claim_id: {
56
+ type: "string",
57
+ description: "UUID of the custody_claims row to respond to.",
58
+ },
59
+ action: {
60
+ type: "string",
61
+ enum: ["accept", "decline", "dispute"],
62
+ },
63
+ reason: {
64
+ type: "string",
65
+ description: "Required when action='dispute'. Optional for decline.",
66
+ },
67
+ },
68
+ required: ["claim_id", "action"],
69
+ },
70
+ annotations: {
71
+ title: "respond to a custody claim",
72
+ destructiveHint: false,
73
+ idempotentHint: false,
74
+ },
75
+ },
76
+ executor: this.respond.bind(this),
77
+ },
78
+ {
79
+ definition: {
80
+ name: "pica_custody_list",
81
+ description: "List custody claims for your organisation — both incoming " +
82
+ "(claims others filed against your custody) and outgoing (claims you filed). " +
83
+ "Defaults to pending claims only. Available to any authenticated org member.",
84
+ inputSchema: {
85
+ type: "object",
86
+ properties: {
87
+ direction: {
88
+ type: "string",
89
+ enum: ["incoming", "outgoing", "both"],
90
+ description: "Default: both.",
91
+ },
92
+ status: {
93
+ type: "string",
94
+ description: "Filter by status (pending|accepted|declined|disputed|auto_approved|withdrawn|expired|all). Default: pending.",
95
+ },
96
+ limit: {
97
+ type: "number",
98
+ description: "1..200. Default 50.",
99
+ },
100
+ },
101
+ },
102
+ annotations: {
103
+ title: "list custody claims",
104
+ readOnlyHint: true,
105
+ idempotentHint: true,
106
+ },
107
+ },
108
+ executor: this.list.bind(this),
109
+ },
110
+ {
111
+ definition: {
112
+ name: "pica_custody_history",
113
+ description: "Return custody-related provenance_history rows for a work. Every row " +
114
+ "includes an attestation_hash so the history is cryptographically anchored. " +
115
+ "Use this to audit who changed custody when. Available to any authenticated org member.",
116
+ inputSchema: {
117
+ type: "object",
118
+ properties: {
119
+ work_id: {
120
+ type: "string",
121
+ description: "UUID of the work whose history to fetch.",
122
+ },
123
+ change_type: {
124
+ type: "string",
125
+ description: "Filter to one change_type (custody_claimed|custody_transferred|custody_released|custody_expired|custody_transfer_auto) or 'all'. Default 'all'.",
126
+ },
127
+ limit: {
128
+ type: "number",
129
+ description: "1..500. Default 100.",
130
+ },
131
+ },
132
+ required: ["work_id"],
133
+ },
134
+ annotations: {
135
+ title: "custody history",
136
+ readOnlyHint: true,
137
+ idempotentHint: true,
138
+ },
139
+ },
140
+ executor: this.history.bind(this),
141
+ },
142
+ {
143
+ definition: {
144
+ name: "pica_custody_resolve_pending",
145
+ description: "Preview works where this org (or a specific global_publisher_id) is named " +
146
+ "as canonical custodian via work_custodians.custodian_global_publisher_id but " +
147
+ "has not yet been claimed via a PICA org membership. The 'Warner Chappell signs " +
148
+ "up and finds 38 works waiting' view. Read-only — use pica_custody_reconcile " +
149
+ "to actually claim them. Admin/owner access required.",
150
+ inputSchema: {
151
+ type: "object",
152
+ properties: {
153
+ global_publisher_id: {
154
+ type: "string",
155
+ description: "Optional. If omitted, uses the caller org's own global_publisher_id bridge.",
156
+ },
157
+ },
158
+ },
159
+ annotations: {
160
+ title: "resolve pending custody",
161
+ readOnlyHint: true,
162
+ idempotentHint: true,
163
+ },
164
+ },
165
+ executor: this.resolvePending.bind(this),
166
+ },
167
+ {
168
+ definition: {
169
+ name: "pica_custody_reconcile",
170
+ description: "Bulk-claim every work where your org (or a specific global_publisher_id) " +
171
+ "is named as canonical custodian but hasn't been locally claimed yet. Writes " +
172
+ "one custody_claims row per matching work. Default is dry-run — pass confirm=true " +
173
+ "to execute. Admin/owner access required.",
174
+ inputSchema: {
175
+ type: "object",
176
+ properties: {
177
+ global_publisher_id: { type: "string" },
178
+ confirm: {
179
+ type: "boolean",
180
+ description: "Required to actually write claims. Default false = dry-run.",
181
+ },
182
+ },
183
+ },
184
+ annotations: {
185
+ title: "reconcile custody",
186
+ destructiveHint: false,
187
+ idempotentHint: false,
188
+ },
189
+ },
190
+ executor: this.reconcile.bind(this),
191
+ },
192
+ ];
193
+ }
194
+ async claim(args) {
195
+ const data = await this.pica.custody.claim({
196
+ work_id: args.work_id,
197
+ chain: args.chain,
198
+ reason: args.reason,
199
+ });
200
+ return formatSuccess(`Custody claim created (${args.chain} chain). The current custodian has 7 days to respond before the claim auto-approves.`, data);
201
+ }
202
+ async respond(args) {
203
+ const data = await this.pica.custody.respond({
204
+ claim_id: args.claim_id,
205
+ action: args.action,
206
+ reason: args.reason,
207
+ });
208
+ const verb = args.action === "accept"
209
+ ? "accepted"
210
+ : args.action === "decline"
211
+ ? "declined"
212
+ : "disputed";
213
+ return formatSuccess(`Custody claim ${verb}.`, data);
214
+ }
215
+ async list(args) {
216
+ const data = await this.pica.custody.list({
217
+ direction: args.direction,
218
+ status: args.status,
219
+ limit: args.limit,
220
+ });
221
+ const incoming = data?.incoming ?? [];
222
+ const outgoing = data?.outgoing ?? [];
223
+ const hints = [];
224
+ if (incoming.length > 0) {
225
+ hints.push({
226
+ gap: "custody_claims_incoming",
227
+ suggestion: `You have ${incoming.length} incoming custody claim(s) — respond via pica_custody_respond before the 7-day window closes.`,
228
+ count: incoming.length,
229
+ severity: "important",
230
+ });
231
+ }
232
+ return formatSuccess(`Found ${incoming.length} incoming + ${outgoing.length} outgoing custody claim(s).`, data, hints);
233
+ }
234
+ async history(args) {
235
+ const data = await this.pica.custody.history({
236
+ work_id: args.work_id,
237
+ change_type: args.change_type,
238
+ limit: args.limit,
239
+ });
240
+ const count = data?.count ?? 0;
241
+ return formatSuccess(count > 0
242
+ ? `Returned ${count} custody history row(s) for the work.`
243
+ : "No custody history rows for this work.", data);
244
+ }
245
+ async resolvePending(args) {
246
+ const data = await this.pica.custody.resolvePending({
247
+ global_publisher_id: args.global_publisher_id,
248
+ });
249
+ const count = data?.count ?? 0;
250
+ const hints = [];
251
+ if (count > 0) {
252
+ hints.push({
253
+ gap: "custody_inheritable",
254
+ suggestion: `${count} work(s) reference your publisher identity but haven't been claimed — run pica_custody_reconcile with confirm=true to claim them in bulk.`,
255
+ count,
256
+ severity: "important",
257
+ });
258
+ }
259
+ return formatSuccess(count > 0
260
+ ? `${count} inheritable work(s) found.`
261
+ : "No inheritable works found.", data, hints);
262
+ }
263
+ async reconcile(args) {
264
+ const data = await this.pica.custody.reconcile({
265
+ global_publisher_id: args.global_publisher_id,
266
+ confirm: args.confirm === true,
267
+ });
268
+ if (data?.dry_run) {
269
+ return formatSuccess(`Dry run — ${data.would_claim ?? 0} claim(s) would be created. Pass confirm=true to execute.`, data);
270
+ }
271
+ return formatSuccess(`Reconciliation complete — ${data?.claimed ?? 0} claimed, ${data?.failed ?? 0} failed.`, data);
272
+ }
273
+ }
274
+ //# sourceMappingURL=custody.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"custody.js","sourceRoot":"","sources":["../../src/tools/custody.ts"],"names":[],"mappings":"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"}
@@ -1 +1 @@
1
- {"version":3,"file":"enrichment.d.ts","sourceRoot":"","sources":["../../src/tools/enrichment.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAKtE,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YA4H3D,oBAAoB;YAOpB,aAAa;YAKb,qBAAqB;YASrB,iBAAiB;YAOjB,iBAAiB;YAuBjB,iBAAiB;CAMhC"}
1
+ {"version":3,"file":"enrichment.d.ts","sourceRoot":"","sources":["../../src/tools/enrichment.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAKtE,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YAgJ3D,oBAAoB;YAOpB,aAAa;YAKb,qBAAqB;YASrB,iBAAiB;YAOjB,iBAAiB;YAuBjB,iBAAiB;CAMhC"}