@yolk-sdk/connectors 0.1.0-canary.13 → 0.1.0-canary.130
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.
- package/README.md +1824 -34
- package/dist/action.d.mts +57 -12
- package/dist/action.d.mts.map +1 -1
- package/dist/action.mjs +26 -11
- package/dist/action.mjs.map +1 -1
- package/dist/afloat/conformance/fixtures.d.mts +27 -0
- package/dist/afloat/conformance/fixtures.d.mts.map +1 -0
- package/dist/afloat/conformance/fixtures.mjs +86 -0
- package/dist/afloat/conformance/fixtures.mjs.map +1 -0
- package/dist/afloat/conformance/index.d.mts +6 -0
- package/dist/afloat/conformance/index.mjs +6 -0
- package/dist/afloat/conformance/seeds.d.mts +40 -0
- package/dist/afloat/conformance/seeds.d.mts.map +1 -0
- package/dist/afloat/conformance/seeds.mjs +46 -0
- package/dist/afloat/conformance/seeds.mjs.map +1 -0
- package/dist/afloat/conformance/target.d.mts +60 -0
- package/dist/afloat/conformance/target.d.mts.map +1 -0
- package/dist/afloat/conformance/target.mjs +74 -0
- package/dist/afloat/conformance/target.mjs.map +1 -0
- package/dist/afloat/conformance/tools.d.mts +4 -0
- package/dist/afloat/conformance/tools.d.mts.map +1 -0
- package/dist/afloat/conformance/tools.mjs +860 -0
- package/dist/afloat/conformance/tools.mjs.map +1 -0
- package/dist/afloat/conformance/wire.d.mts +54 -0
- package/dist/afloat/conformance/wire.d.mts.map +1 -0
- package/dist/afloat/conformance/wire.mjs +236 -0
- package/dist/afloat/conformance/wire.mjs.map +1 -0
- package/dist/afloat/index.d.mts +25 -0
- package/dist/afloat/index.d.mts.map +1 -0
- package/dist/afloat/index.mjs +64 -0
- package/dist/afloat/index.mjs.map +1 -0
- package/dist/agent.d.mts +36 -10
- package/dist/agent.d.mts.map +1 -1
- package/dist/agent.mjs +101 -37
- package/dist/agent.mjs.map +1 -1
- package/dist/base64-internal.d.mts +11 -0
- package/dist/base64-internal.d.mts.map +1 -0
- package/dist/base64-internal.mjs +22 -0
- package/dist/base64-internal.mjs.map +1 -0
- package/dist/binary-http.d.mts +41 -0
- package/dist/binary-http.d.mts.map +1 -0
- package/dist/binary-http.mjs +14 -0
- package/dist/binary-http.mjs.map +1 -0
- package/dist/binary-write-http.d.mts +64 -0
- package/dist/binary-write-http.d.mts.map +1 -0
- package/dist/binary-write-http.mjs +6 -0
- package/dist/binary-write-http.mjs.map +1 -0
- package/dist/config.d.mts +2 -6
- package/dist/config.d.mts.map +1 -1
- package/dist/config.mjs +6 -8
- package/dist/config.mjs.map +1 -1
- package/dist/conformance/cleanup-reporter.d.mts +66 -0
- package/dist/conformance/cleanup-reporter.d.mts.map +1 -0
- package/dist/conformance/cleanup-reporter.mjs +79 -0
- package/dist/conformance/cleanup-reporter.mjs.map +1 -0
- package/dist/conformance/index.d.mts +64 -0
- package/dist/conformance/index.d.mts.map +1 -0
- package/dist/conformance/index.mjs +215 -0
- package/dist/conformance/index.mjs.map +1 -0
- package/dist/conformance/owned-write.d.mts +82 -0
- package/dist/conformance/owned-write.d.mts.map +1 -0
- package/dist/conformance/owned-write.mjs +91 -0
- package/dist/conformance/owned-write.mjs.map +1 -0
- package/dist/connector.d.mts +5 -9
- package/dist/connector.d.mts.map +1 -1
- package/dist/connector.mjs +1 -2
- package/dist/credential.d.mts +31 -28
- package/dist/credential.d.mts.map +1 -1
- package/dist/credential.mjs +29 -15
- package/dist/credential.mjs.map +1 -1
- package/dist/dropbox/conformance/cases.d.mts +140 -0
- package/dist/dropbox/conformance/cases.d.mts.map +1 -0
- package/dist/dropbox/conformance/cases.mjs +708 -0
- package/dist/dropbox/conformance/cases.mjs.map +1 -0
- package/dist/dropbox/conformance/copy-move-metadata.d.mts +12 -0
- package/dist/dropbox/conformance/copy-move-metadata.d.mts.map +1 -0
- package/dist/dropbox/conformance/copy-move-metadata.mjs +113 -0
- package/dist/dropbox/conformance/copy-move-metadata.mjs.map +1 -0
- package/dist/dropbox/conformance/create-folder-conflict.d.mts +13 -0
- package/dist/dropbox/conformance/create-folder-conflict.d.mts.map +1 -0
- package/dist/dropbox/conformance/create-folder-conflict.mjs +81 -0
- package/dist/dropbox/conformance/create-folder-conflict.mjs.map +1 -0
- package/dist/dropbox/conformance/delete-then-not-found.d.mts +12 -0
- package/dist/dropbox/conformance/delete-then-not-found.d.mts.map +1 -0
- package/dist/dropbox/conformance/delete-then-not-found.mjs +77 -0
- package/dist/dropbox/conformance/delete-then-not-found.mjs.map +1 -0
- package/dist/dropbox/conformance/index.d.mts +15 -0
- package/dist/dropbox/conformance/index.d.mts.map +1 -0
- package/dist/dropbox/conformance/index.mjs +25 -0
- package/dist/dropbox/conformance/index.mjs.map +1 -0
- package/dist/dropbox/conformance/list-folder-paging.d.mts +12 -0
- package/dist/dropbox/conformance/list-folder-paging.d.mts.map +1 -0
- package/dist/dropbox/conformance/list-folder-paging.mjs +88 -0
- package/dist/dropbox/conformance/list-folder-paging.mjs.map +1 -0
- package/dist/dropbox/conformance/not-found-envelope.d.mts +12 -0
- package/dist/dropbox/conformance/not-found-envelope.d.mts.map +1 -0
- package/dist/dropbox/conformance/not-found-envelope.mjs +35 -0
- package/dist/dropbox/conformance/not-found-envelope.mjs.map +1 -0
- package/dist/dropbox/conformance/path-lower-lookup.d.mts +12 -0
- package/dist/dropbox/conformance/path-lower-lookup.d.mts.map +1 -0
- package/dist/dropbox/conformance/path-lower-lookup.mjs +60 -0
- package/dist/dropbox/conformance/path-lower-lookup.mjs.map +1 -0
- package/dist/dropbox/conformance/search-continue.d.mts +11 -0
- package/dist/dropbox/conformance/search-continue.d.mts.map +1 -0
- package/dist/dropbox/conformance/search-continue.mjs +78 -0
- package/dist/dropbox/conformance/search-continue.mjs.map +1 -0
- package/dist/dropbox/conformance/seeds.d.mts +9 -0
- package/dist/dropbox/conformance/seeds.d.mts.map +1 -0
- package/dist/dropbox/conformance/seeds.mjs +18 -0
- package/dist/dropbox/conformance/seeds.mjs.map +1 -0
- package/dist/dropbox/conformance/upload-rev-precondition.d.mts +13 -0
- package/dist/dropbox/conformance/upload-rev-precondition.d.mts.map +1 -0
- package/dist/dropbox/conformance/upload-rev-precondition.mjs +128 -0
- package/dist/dropbox/conformance/upload-rev-precondition.mjs.map +1 -0
- package/dist/dropbox/download.d.mts +49 -0
- package/dist/dropbox/download.d.mts.map +1 -0
- package/dist/dropbox/download.mjs +146 -0
- package/dist/dropbox/download.mjs.map +1 -0
- package/dist/dropbox/index.d.mts +124 -0
- package/dist/dropbox/index.d.mts.map +1 -0
- package/dist/dropbox/index.mjs +516 -0
- package/dist/dropbox/index.mjs.map +1 -0
- package/dist/dropbox/shared.d.mts +28 -0
- package/dist/dropbox/shared.d.mts.map +1 -0
- package/dist/dropbox/shared.mjs +60 -0
- package/dist/dropbox/shared.mjs.map +1 -0
- package/dist/dropbox/write.d.mts +30 -0
- package/dist/dropbox/write.d.mts.map +1 -0
- package/dist/dropbox/write.mjs +60 -0
- package/dist/dropbox/write.mjs.map +1 -0
- package/dist/email/conformance/acceptance-not-delivery.d.mts +7 -0
- package/dist/email/conformance/acceptance-not-delivery.d.mts.map +1 -0
- package/dist/email/conformance/acceptance-not-delivery.mjs +27 -0
- package/dist/email/conformance/acceptance-not-delivery.mjs.map +1 -0
- package/dist/email/conformance/backend.d.mts +80 -0
- package/dist/email/conformance/backend.d.mts.map +1 -0
- package/dist/email/conformance/backend.mjs +189 -0
- package/dist/email/conformance/backend.mjs.map +1 -0
- package/dist/email/conformance/cases.d.mts +145 -0
- package/dist/email/conformance/cases.d.mts.map +1 -0
- package/dist/email/conformance/cases.mjs +864 -0
- package/dist/email/conformance/cases.mjs.map +1 -0
- package/dist/email/conformance/draft-drafts-discovery.d.mts +7 -0
- package/dist/email/conformance/draft-drafts-discovery.d.mts.map +1 -0
- package/dist/email/conformance/draft-drafts-discovery.mjs +55 -0
- package/dist/email/conformance/draft-drafts-discovery.mjs.map +1 -0
- package/dist/email/conformance/filtered-list-no-fallback.d.mts +7 -0
- package/dist/email/conformance/filtered-list-no-fallback.d.mts.map +1 -0
- package/dist/email/conformance/filtered-list-no-fallback.mjs +21 -0
- package/dist/email/conformance/filtered-list-no-fallback.mjs.map +1 -0
- package/dist/email/conformance/index.d.mts +18 -0
- package/dist/email/conformance/index.d.mts.map +1 -0
- package/dist/email/conformance/index.mjs +30 -0
- package/dist/email/conformance/index.mjs.map +1 -0
- package/dist/email/conformance/legacy-host-sent-copy.d.mts +4 -0
- package/dist/email/conformance/legacy-host-sent-copy.d.mts.map +1 -0
- package/dist/email/conformance/legacy-host-sent-copy.mjs +25 -0
- package/dist/email/conformance/legacy-host-sent-copy.mjs.map +1 -0
- package/dist/email/conformance/list-and-get-headers.d.mts +8 -0
- package/dist/email/conformance/list-and-get-headers.d.mts.map +1 -0
- package/dist/email/conformance/list-and-get-headers.mjs +39 -0
- package/dist/email/conformance/list-and-get-headers.mjs.map +1 -0
- package/dist/email/conformance/move-destination-ids.d.mts +8 -0
- package/dist/email/conformance/move-destination-ids.d.mts.map +1 -0
- package/dist/email/conformance/move-destination-ids.mjs +90 -0
- package/dist/email/conformance/move-destination-ids.mjs.map +1 -0
- package/dist/email/conformance/pop3-rejections.d.mts +7 -0
- package/dist/email/conformance/pop3-rejections.d.mts.map +1 -0
- package/dist/email/conformance/pop3-rejections.mjs +40 -0
- package/dist/email/conformance/pop3-rejections.mjs.map +1 -0
- package/dist/email/conformance/seeds.d.mts +8 -0
- package/dist/email/conformance/seeds.d.mts.map +1 -0
- package/dist/email/conformance/seeds.mjs +21 -0
- package/dist/email/conformance/seeds.mjs.map +1 -0
- package/dist/email/conformance/sent-copy-statuses.d.mts +8 -0
- package/dist/email/conformance/sent-copy-statuses.d.mts.map +1 -0
- package/dist/email/conformance/sent-copy-statuses.mjs +72 -0
- package/dist/email/conformance/sent-copy-statuses.mjs.map +1 -0
- package/dist/email/conformance/set-read-and-flag.d.mts +7 -0
- package/dist/email/conformance/set-read-and-flag.d.mts.map +1 -0
- package/dist/email/conformance/set-read-and-flag.mjs +75 -0
- package/dist/email/conformance/set-read-and-flag.mjs.map +1 -0
- package/dist/email/conformance/synthetic.d.mts +72 -0
- package/dist/email/conformance/synthetic.d.mts.map +1 -0
- package/dist/email/conformance/synthetic.mjs +147 -0
- package/dist/email/conformance/synthetic.mjs.map +1 -0
- package/dist/email/conformance/trash-untrash-to-inbox.d.mts +8 -0
- package/dist/email/conformance/trash-untrash-to-inbox.d.mts.map +1 -0
- package/dist/email/conformance/trash-untrash-to-inbox.mjs +89 -0
- package/dist/email/conformance/trash-untrash-to-inbox.mjs.map +1 -0
- package/dist/email/index.d.mts +749 -0
- package/dist/email/index.d.mts.map +1 -0
- package/dist/email/index.mjs +1185 -0
- package/dist/email/index.mjs.map +1 -0
- package/dist/email-batch.d.mts +62 -0
- package/dist/email-batch.d.mts.map +1 -0
- package/dist/email-batch.mjs +88 -0
- package/dist/email-batch.mjs.map +1 -0
- package/dist/error.d.mts +5 -8
- package/dist/error.d.mts.map +1 -1
- package/dist/error.mjs +3 -3
- package/dist/error.mjs.map +1 -1
- package/dist/figma/index.d.mts +19 -22
- package/dist/figma/index.d.mts.map +1 -1
- package/dist/figma/index.mjs +21 -25
- package/dist/figma/index.mjs.map +1 -1
- package/dist/file-output.d.mts +13 -0
- package/dist/file-output.d.mts.map +1 -0
- package/dist/file-output.mjs +101 -0
- package/dist/file-output.mjs.map +1 -0
- package/dist/file-transfer.d.mts +19 -0
- package/dist/file-transfer.d.mts.map +1 -0
- package/dist/file-transfer.mjs +27 -0
- package/dist/file-transfer.mjs.map +1 -0
- package/dist/fortnox/articles.d.mts +664 -0
- package/dist/fortnox/articles.d.mts.map +1 -0
- package/dist/fortnox/articles.mjs +222 -0
- package/dist/fortnox/articles.mjs.map +1 -0
- package/dist/fortnox/conformance/cases.d.mts +96 -0
- package/dist/fortnox/conformance/cases.d.mts.map +1 -0
- package/dist/fortnox/conformance/cases.mjs +523 -0
- package/dist/fortnox/conformance/cases.mjs.map +1 -0
- package/dist/fortnox/conformance/customer-empty-string.d.mts +12 -0
- package/dist/fortnox/conformance/customer-empty-string.d.mts.map +1 -0
- package/dist/fortnox/conformance/customer-empty-string.mjs +120 -0
- package/dist/fortnox/conformance/customer-empty-string.mjs.map +1 -0
- package/dist/fortnox/conformance/index.d.mts +14 -0
- package/dist/fortnox/conformance/index.d.mts.map +1 -0
- package/dist/fortnox/conformance/index.mjs +23 -0
- package/dist/fortnox/conformance/index.mjs.map +1 -0
- package/dist/fortnox/conformance/invoice-list-populated.d.mts +12 -0
- package/dist/fortnox/conformance/invoice-list-populated.d.mts.map +1 -0
- package/dist/fortnox/conformance/invoice-list-populated.mjs +34 -0
- package/dist/fortnox/conformance/invoice-list-populated.mjs.map +1 -0
- package/dist/fortnox/conformance/invoice-payment-filters.d.mts +13 -0
- package/dist/fortnox/conformance/invoice-payment-filters.d.mts.map +1 -0
- package/dist/fortnox/conformance/invoice-payment-filters.mjs +61 -0
- package/dist/fortnox/conformance/invoice-payment-filters.mjs.map +1 -0
- package/dist/fortnox/conformance/invoice-preview-pdf.d.mts +12 -0
- package/dist/fortnox/conformance/invoice-preview-pdf.d.mts.map +1 -0
- package/dist/fortnox/conformance/invoice-preview-pdf.mjs +33 -0
- package/dist/fortnox/conformance/invoice-preview-pdf.mjs.map +1 -0
- package/dist/fortnox/conformance/invoice-row-discount.d.mts +14 -0
- package/dist/fortnox/conformance/invoice-row-discount.d.mts.map +1 -0
- package/dist/fortnox/conformance/invoice-row-discount.mjs +216 -0
- package/dist/fortnox/conformance/invoice-row-discount.mjs.map +1 -0
- package/dist/fortnox/conformance/invoice-send-email.d.mts +12 -0
- package/dist/fortnox/conformance/invoice-send-email.d.mts.map +1 -0
- package/dist/fortnox/conformance/invoice-send-email.mjs +45 -0
- package/dist/fortnox/conformance/invoice-send-email.mjs.map +1 -0
- package/dist/fortnox/conformance/seeds.d.mts +8 -0
- package/dist/fortnox/conformance/seeds.d.mts.map +1 -0
- package/dist/fortnox/conformance/seeds.mjs +18 -0
- package/dist/fortnox/conformance/seeds.mjs.map +1 -0
- package/dist/fortnox/conformance/write-rejection.d.mts +12 -0
- package/dist/fortnox/conformance/write-rejection.d.mts.map +1 -0
- package/dist/fortnox/conformance/write-rejection.mjs +52 -0
- package/dist/fortnox/conformance/write-rejection.mjs.map +1 -0
- package/dist/fortnox/cost-centers.d.mts +157 -0
- package/dist/fortnox/cost-centers.d.mts.map +1 -0
- package/dist/fortnox/cost-centers.mjs +103 -0
- package/dist/fortnox/cost-centers.mjs.map +1 -0
- package/dist/fortnox/fields.d.mts +21 -0
- package/dist/fortnox/fields.d.mts.map +1 -0
- package/dist/fortnox/fields.mjs +36 -0
- package/dist/fortnox/fields.mjs.map +1 -0
- package/dist/fortnox/files.d.mts +56 -0
- package/dist/fortnox/files.d.mts.map +1 -0
- package/dist/fortnox/files.mjs +92 -0
- package/dist/fortnox/files.mjs.map +1 -0
- package/dist/fortnox/inbox.d.mts +111 -0
- package/dist/fortnox/inbox.d.mts.map +1 -0
- package/dist/fortnox/inbox.mjs +205 -0
- package/dist/fortnox/inbox.mjs.map +1 -0
- package/dist/fortnox/index.d.mts +208 -0
- package/dist/fortnox/index.d.mts.map +1 -0
- package/dist/fortnox/index.mjs +199 -0
- package/dist/fortnox/index.mjs.map +1 -0
- package/dist/fortnox/oauth.d.mts +36 -0
- package/dist/fortnox/oauth.d.mts.map +1 -0
- package/dist/fortnox/oauth.mjs +57 -0
- package/dist/fortnox/oauth.mjs.map +1 -0
- package/dist/fortnox/offers.d.mts +541 -0
- package/dist/fortnox/offers.d.mts.map +1 -0
- package/dist/fortnox/offers.mjs +319 -0
- package/dist/fortnox/offers.mjs.map +1 -0
- package/dist/fortnox/payments.d.mts +570 -0
- package/dist/fortnox/payments.d.mts.map +1 -0
- package/dist/fortnox/payments.mjs +329 -0
- package/dist/fortnox/payments.mjs.map +1 -0
- package/dist/fortnox/prices.d.mts +310 -0
- package/dist/fortnox/prices.d.mts.map +1 -0
- package/dist/fortnox/prices.mjs +208 -0
- package/dist/fortnox/prices.mjs.map +1 -0
- package/dist/fortnox/print-templates.d.mts +24 -0
- package/dist/fortnox/print-templates.d.mts.map +1 -0
- package/dist/fortnox/print-templates.mjs +31 -0
- package/dist/fortnox/print-templates.mjs.map +1 -0
- package/dist/fortnox/profile.d.mts +19 -0
- package/dist/fortnox/profile.d.mts.map +1 -0
- package/dist/fortnox/profile.mjs +27 -0
- package/dist/fortnox/profile.mjs.map +1 -0
- package/dist/fortnox/schemas.d.mts +523 -0
- package/dist/fortnox/schemas.d.mts.map +1 -0
- package/dist/fortnox/schemas.mjs +340 -0
- package/dist/fortnox/schemas.mjs.map +1 -0
- package/dist/fortnox/settings-registers.d.mts +331 -0
- package/dist/fortnox/settings-registers.d.mts.map +1 -0
- package/dist/fortnox/settings-registers.mjs +461 -0
- package/dist/fortnox/settings-registers.mjs.map +1 -0
- package/dist/fortnox/settings.d.mts +186 -0
- package/dist/fortnox/settings.d.mts.map +1 -0
- package/dist/fortnox/settings.mjs +173 -0
- package/dist/fortnox/settings.mjs.map +1 -0
- package/dist/fortnox/shared.d.mts +75 -0
- package/dist/fortnox/shared.d.mts.map +1 -0
- package/dist/fortnox/shared.mjs +132 -0
- package/dist/fortnox/shared.mjs.map +1 -0
- package/dist/fortnox/transfer.d.mts +14 -0
- package/dist/fortnox/transfer.d.mts.map +1 -0
- package/dist/fortnox/transfer.mjs +30 -0
- package/dist/fortnox/transfer.mjs.map +1 -0
- package/dist/fortnox/wire.d.mts +68 -0
- package/dist/fortnox/wire.d.mts.map +1 -0
- package/dist/fortnox/wire.mjs +91 -0
- package/dist/fortnox/wire.mjs.map +1 -0
- package/dist/github/app-token.d.mts +35 -0
- package/dist/github/app-token.d.mts.map +1 -0
- package/dist/github/app-token.mjs +235 -0
- package/dist/github/app-token.mjs.map +1 -0
- package/dist/github/attachments.d.mts +39 -0
- package/dist/github/attachments.d.mts.map +1 -0
- package/dist/github/attachments.mjs +151 -0
- package/dist/github/attachments.mjs.map +1 -0
- package/dist/github/comments.d.mts +316 -0
- package/dist/github/comments.d.mts.map +1 -0
- package/dist/github/comments.mjs +393 -0
- package/dist/github/comments.mjs.map +1 -0
- package/dist/github/conformance/cases.d.mts +135 -0
- package/dist/github/conformance/cases.d.mts.map +1 -0
- package/dist/github/conformance/cases.mjs +616 -0
- package/dist/github/conformance/cases.mjs.map +1 -0
- package/dist/github/conformance/comment-lifecycle.d.mts +12 -0
- package/dist/github/conformance/comment-lifecycle.d.mts.map +1 -0
- package/dist/github/conformance/comment-lifecycle.mjs +71 -0
- package/dist/github/conformance/comment-lifecycle.mjs.map +1 -0
- package/dist/github/conformance/file-contents.d.mts +12 -0
- package/dist/github/conformance/file-contents.d.mts.map +1 -0
- package/dist/github/conformance/file-contents.mjs +47 -0
- package/dist/github/conformance/file-contents.mjs.map +1 -0
- package/dist/github/conformance/index.d.mts +14 -0
- package/dist/github/conformance/index.d.mts.map +1 -0
- package/dist/github/conformance/index.mjs +23 -0
- package/dist/github/conformance/index.mjs.map +1 -0
- package/dist/github/conformance/issue-labels.d.mts +13 -0
- package/dist/github/conformance/issue-labels.d.mts.map +1 -0
- package/dist/github/conformance/issue-labels.mjs +91 -0
- package/dist/github/conformance/issue-labels.mjs.map +1 -0
- package/dist/github/conformance/issue-lifecycle.d.mts +12 -0
- package/dist/github/conformance/issue-lifecycle.d.mts.map +1 -0
- package/dist/github/conformance/issue-lifecycle.mjs +93 -0
- package/dist/github/conformance/issue-lifecycle.mjs.map +1 -0
- package/dist/github/conformance/labels-paging.d.mts +12 -0
- package/dist/github/conformance/labels-paging.d.mts.map +1 -0
- package/dist/github/conformance/labels-paging.mjs +61 -0
- package/dist/github/conformance/labels-paging.mjs.map +1 -0
- package/dist/github/conformance/not-found-envelope.d.mts +12 -0
- package/dist/github/conformance/not-found-envelope.d.mts.map +1 -0
- package/dist/github/conformance/not-found-envelope.mjs +31 -0
- package/dist/github/conformance/not-found-envelope.mjs.map +1 -0
- package/dist/github/conformance/seeds.d.mts +9 -0
- package/dist/github/conformance/seeds.d.mts.map +1 -0
- package/dist/github/conformance/seeds.mjs +18 -0
- package/dist/github/conformance/seeds.mjs.map +1 -0
- package/dist/github/conformance/synthetic.d.mts +48 -0
- package/dist/github/conformance/synthetic.d.mts.map +1 -0
- package/dist/github/conformance/synthetic.mjs +100 -0
- package/dist/github/conformance/synthetic.mjs.map +1 -0
- package/dist/github/conformance/validation-envelope.d.mts +12 -0
- package/dist/github/conformance/validation-envelope.d.mts.map +1 -0
- package/dist/github/conformance/validation-envelope.mjs +41 -0
- package/dist/github/conformance/validation-envelope.mjs.map +1 -0
- package/dist/github/index.d.mts +955 -0
- package/dist/github/index.d.mts.map +1 -0
- package/dist/github/index.mjs +26 -0
- package/dist/github/index.mjs.map +1 -0
- package/dist/github/issues.d.mts +757 -0
- package/dist/github/issues.d.mts.map +1 -0
- package/dist/github/issues.mjs +585 -0
- package/dist/github/issues.mjs.map +1 -0
- package/dist/github/pulls.d.mts +1045 -0
- package/dist/github/pulls.d.mts.map +1 -0
- package/dist/github/pulls.mjs +881 -0
- package/dist/github/pulls.mjs.map +1 -0
- package/dist/github/repository.d.mts +282 -0
- package/dist/github/repository.d.mts.map +1 -0
- package/dist/github/repository.mjs +396 -0
- package/dist/github/repository.mjs.map +1 -0
- package/dist/github/shared.d.mts +213 -0
- package/dist/github/shared.d.mts.map +1 -0
- package/dist/github/shared.mjs +374 -0
- package/dist/github/shared.mjs.map +1 -0
- package/dist/github/structure.d.mts +730 -0
- package/dist/github/structure.d.mts.map +1 -0
- package/dist/github/structure.mjs +451 -0
- package/dist/github/structure.mjs.map +1 -0
- package/dist/google/calendar.d.mts +227 -38
- package/dist/google/calendar.d.mts.map +1 -1
- package/dist/google/calendar.mjs +70 -32
- package/dist/google/calendar.mjs.map +1 -1
- package/dist/google/conformance/calendar-cases.d.mts +5 -0
- package/dist/google/conformance/calendar-cases.d.mts.map +1 -0
- package/dist/google/conformance/calendar-cases.mjs +214 -0
- package/dist/google/conformance/calendar-cases.mjs.map +1 -0
- package/dist/google/conformance/calendar-deleted-gone.d.mts +12 -0
- package/dist/google/conformance/calendar-deleted-gone.d.mts.map +1 -0
- package/dist/google/conformance/calendar-deleted-gone.mjs +98 -0
- package/dist/google/conformance/calendar-deleted-gone.mjs.map +1 -0
- package/dist/google/conformance/calendar-event-lifecycle.d.mts +12 -0
- package/dist/google/conformance/calendar-event-lifecycle.d.mts.map +1 -0
- package/dist/google/conformance/calendar-event-lifecycle.mjs +112 -0
- package/dist/google/conformance/calendar-event-lifecycle.mjs.map +1 -0
- package/dist/google/conformance/calendar-list-range.d.mts +12 -0
- package/dist/google/conformance/calendar-list-range.d.mts.map +1 -0
- package/dist/google/conformance/calendar-list-range.mjs +108 -0
- package/dist/google/conformance/calendar-list-range.mjs.map +1 -0
- package/dist/google/conformance/cases.d.mts +22 -0
- package/dist/google/conformance/cases.d.mts.map +1 -0
- package/dist/google/conformance/cases.mjs +172 -0
- package/dist/google/conformance/cases.mjs.map +1 -0
- package/dist/google/conformance/drive-cases.d.mts +5 -0
- package/dist/google/conformance/drive-cases.d.mts.map +1 -0
- package/dist/google/conformance/drive-cases.mjs +155 -0
- package/dist/google/conformance/drive-cases.mjs.map +1 -0
- package/dist/google/conformance/drive-folder-lifecycle.d.mts +12 -0
- package/dist/google/conformance/drive-folder-lifecycle.d.mts.map +1 -0
- package/dist/google/conformance/drive-folder-lifecycle.mjs +85 -0
- package/dist/google/conformance/drive-folder-lifecycle.mjs.map +1 -0
- package/dist/google/conformance/drive-get-file-fields.d.mts +12 -0
- package/dist/google/conformance/drive-get-file-fields.d.mts.map +1 -0
- package/dist/google/conformance/drive-get-file-fields.mjs +38 -0
- package/dist/google/conformance/drive-get-file-fields.mjs.map +1 -0
- package/dist/google/conformance/drive-list-paging.d.mts +12 -0
- package/dist/google/conformance/drive-list-paging.d.mts.map +1 -0
- package/dist/google/conformance/drive-list-paging.mjs +49 -0
- package/dist/google/conformance/drive-list-paging.mjs.map +1 -0
- package/dist/google/conformance/gmail-attachment.d.mts +12 -0
- package/dist/google/conformance/gmail-attachment.d.mts.map +1 -0
- package/dist/google/conformance/gmail-attachment.mjs +105 -0
- package/dist/google/conformance/gmail-attachment.mjs.map +1 -0
- package/dist/google/conformance/gmail-cases.d.mts +13 -0
- package/dist/google/conformance/gmail-cases.d.mts.map +1 -0
- package/dist/google/conformance/gmail-cases.mjs +542 -0
- package/dist/google/conformance/gmail-cases.mjs.map +1 -0
- package/dist/google/conformance/gmail-draft-lifecycle.d.mts +13 -0
- package/dist/google/conformance/gmail-draft-lifecycle.d.mts.map +1 -0
- package/dist/google/conformance/gmail-draft-lifecycle.mjs +200 -0
- package/dist/google/conformance/gmail-draft-lifecycle.mjs.map +1 -0
- package/dist/google/conformance/gmail-label-lifecycle.d.mts +12 -0
- package/dist/google/conformance/gmail-label-lifecycle.d.mts.map +1 -0
- package/dist/google/conformance/gmail-label-lifecycle.mjs +85 -0
- package/dist/google/conformance/gmail-label-lifecycle.mjs.map +1 -0
- package/dist/google/conformance/gmail-list-paging.d.mts +12 -0
- package/dist/google/conformance/gmail-list-paging.d.mts.map +1 -0
- package/dist/google/conformance/gmail-list-paging.mjs +78 -0
- package/dist/google/conformance/gmail-list-paging.mjs.map +1 -0
- package/dist/google/conformance/gmail-list-threads-paging.d.mts +13 -0
- package/dist/google/conformance/gmail-list-threads-paging.d.mts.map +1 -0
- package/dist/google/conformance/gmail-list-threads-paging.mjs +100 -0
- package/dist/google/conformance/gmail-list-threads-paging.mjs.map +1 -0
- package/dist/google/conformance/gmail-metadata-headers.d.mts +13 -0
- package/dist/google/conformance/gmail-metadata-headers.d.mts.map +1 -0
- package/dist/google/conformance/gmail-metadata-headers.mjs +88 -0
- package/dist/google/conformance/gmail-metadata-headers.mjs.map +1 -0
- package/dist/google/conformance/gmail-not-found-envelope.d.mts +12 -0
- package/dist/google/conformance/gmail-not-found-envelope.d.mts.map +1 -0
- package/dist/google/conformance/gmail-not-found-envelope.mjs +30 -0
- package/dist/google/conformance/gmail-not-found-envelope.mjs.map +1 -0
- package/dist/google/conformance/gmail-send-practice.d.mts +17 -0
- package/dist/google/conformance/gmail-send-practice.d.mts.map +1 -0
- package/dist/google/conformance/gmail-send-practice.mjs +109 -0
- package/dist/google/conformance/gmail-send-practice.mjs.map +1 -0
- package/dist/google/conformance/gmail-trash-untrash.d.mts +12 -0
- package/dist/google/conformance/gmail-trash-untrash.d.mts.map +1 -0
- package/dist/google/conformance/gmail-trash-untrash.mjs +71 -0
- package/dist/google/conformance/gmail-trash-untrash.mjs.map +1 -0
- package/dist/google/conformance/index.d.mts +26 -0
- package/dist/google/conformance/index.d.mts.map +1 -0
- package/dist/google/conformance/index.mjs +43 -0
- package/dist/google/conformance/index.mjs.map +1 -0
- package/dist/google/conformance/seeds.d.mts +10 -0
- package/dist/google/conformance/seeds.d.mts.map +1 -0
- package/dist/google/conformance/seeds.mjs +23 -0
- package/dist/google/conformance/seeds.mjs.map +1 -0
- package/dist/google/conformance/shared.d.mts +216 -0
- package/dist/google/conformance/shared.d.mts.map +1 -0
- package/dist/google/conformance/shared.mjs +243 -0
- package/dist/google/conformance/shared.mjs.map +1 -0
- package/dist/google/conformance/synthetic.d.mts +92 -0
- package/dist/google/conformance/synthetic.d.mts.map +1 -0
- package/dist/google/conformance/synthetic.mjs +243 -0
- package/dist/google/conformance/synthetic.mjs.map +1 -0
- package/dist/google/drive-download.d.mts +44 -0
- package/dist/google/drive-download.d.mts.map +1 -0
- package/dist/google/drive-download.mjs +108 -0
- package/dist/google/drive-download.mjs.map +1 -0
- package/dist/google/drive.d.mts +325 -0
- package/dist/google/drive.d.mts.map +1 -0
- package/dist/google/drive.mjs +510 -0
- package/dist/google/drive.mjs.map +1 -0
- package/dist/google/gmail-download.d.mts +19 -0
- package/dist/google/gmail-download.d.mts.map +1 -0
- package/dist/google/gmail-download.mjs +42 -0
- package/dist/google/gmail-download.mjs.map +1 -0
- package/dist/google/gmail-draft-mime.d.mts +47 -0
- package/dist/google/gmail-draft-mime.d.mts.map +1 -0
- package/dist/google/gmail-draft-mime.mjs +213 -0
- package/dist/google/gmail-draft-mime.mjs.map +1 -0
- package/dist/google/gmail.d.mts +420 -40
- package/dist/google/gmail.d.mts.map +1 -1
- package/dist/google/gmail.mjs +1505 -109
- package/dist/google/gmail.mjs.map +1 -1
- package/dist/google/index.d.mts +11 -10
- package/dist/google/index.d.mts.map +1 -1
- package/dist/google/index.mjs +16 -9
- package/dist/google/index.mjs.map +1 -1
- package/dist/google/oauth.d.mts +39 -14
- package/dist/google/oauth.d.mts.map +1 -1
- package/dist/google/oauth.mjs +88 -5
- package/dist/google/oauth.mjs.map +1 -1
- package/dist/google/shared.d.mts +8 -11
- package/dist/google/shared.d.mts.map +1 -1
- package/dist/google/shared.mjs +80 -21
- package/dist/google/shared.mjs.map +1 -1
- package/dist/http.d.mts +12 -11
- package/dist/http.d.mts.map +1 -1
- package/dist/http.mjs +7 -4
- package/dist/http.mjs.map +1 -1
- package/dist/index.d.mts +12 -6
- package/dist/index.mjs +10 -4
- package/dist/integration.d.mts +8 -10
- package/dist/integration.d.mts.map +1 -1
- package/dist/integration.mjs +16 -10
- package/dist/integration.mjs.map +1 -1
- package/dist/kie/index.d.mts +78 -0
- package/dist/kie/index.d.mts.map +1 -0
- package/dist/kie/index.mjs +307 -0
- package/dist/kie/index.mjs.map +1 -0
- package/dist/linkedin-search/conformance/cases.d.mts +81 -0
- package/dist/linkedin-search/conformance/cases.d.mts.map +1 -0
- package/dist/linkedin-search/conformance/cases.mjs +376 -0
- package/dist/linkedin-search/conformance/cases.mjs.map +1 -0
- package/dist/linkedin-search/conformance/email-lookup.d.mts +12 -0
- package/dist/linkedin-search/conformance/email-lookup.d.mts.map +1 -0
- package/dist/linkedin-search/conformance/email-lookup.mjs +33 -0
- package/dist/linkedin-search/conformance/email-lookup.mjs.map +1 -0
- package/dist/linkedin-search/conformance/enrich-layer-unauthorized.d.mts +13 -0
- package/dist/linkedin-search/conformance/enrich-layer-unauthorized.d.mts.map +1 -0
- package/dist/linkedin-search/conformance/enrich-layer-unauthorized.mjs +52 -0
- package/dist/linkedin-search/conformance/enrich-layer-unauthorized.mjs.map +1 -0
- package/dist/linkedin-search/conformance/exa-unauthorized.d.mts +13 -0
- package/dist/linkedin-search/conformance/exa-unauthorized.d.mts.map +1 -0
- package/dist/linkedin-search/conformance/exa-unauthorized.mjs +45 -0
- package/dist/linkedin-search/conformance/exa-unauthorized.mjs.map +1 -0
- package/dist/linkedin-search/conformance/index.d.mts +14 -0
- package/dist/linkedin-search/conformance/index.d.mts.map +1 -0
- package/dist/linkedin-search/conformance/index.mjs +23 -0
- package/dist/linkedin-search/conformance/index.mjs.map +1 -0
- package/dist/linkedin-search/conformance/num-results-limit.d.mts +14 -0
- package/dist/linkedin-search/conformance/num-results-limit.d.mts.map +1 -0
- package/dist/linkedin-search/conformance/num-results-limit.mjs +89 -0
- package/dist/linkedin-search/conformance/num-results-limit.mjs.map +1 -0
- package/dist/linkedin-search/conformance/people-results.d.mts +13 -0
- package/dist/linkedin-search/conformance/people-results.d.mts.map +1 -0
- package/dist/linkedin-search/conformance/people-results.mjs +60 -0
- package/dist/linkedin-search/conformance/people-results.mjs.map +1 -0
- package/dist/linkedin-search/conformance/profile-not-found.d.mts +12 -0
- package/dist/linkedin-search/conformance/profile-not-found.d.mts.map +1 -0
- package/dist/linkedin-search/conformance/profile-not-found.mjs +37 -0
- package/dist/linkedin-search/conformance/profile-not-found.mjs.map +1 -0
- package/dist/linkedin-search/conformance/profile.d.mts +13 -0
- package/dist/linkedin-search/conformance/profile.d.mts.map +1 -0
- package/dist/linkedin-search/conformance/profile.mjs +38 -0
- package/dist/linkedin-search/conformance/profile.mjs.map +1 -0
- package/dist/linkedin-search/conformance/seeds.d.mts +9 -0
- package/dist/linkedin-search/conformance/seeds.d.mts.map +1 -0
- package/dist/linkedin-search/conformance/seeds.mjs +15 -0
- package/dist/linkedin-search/conformance/seeds.mjs.map +1 -0
- package/dist/linkedin-search/index.d.mts +22 -25
- package/dist/linkedin-search/index.d.mts.map +1 -1
- package/dist/linkedin-search/index.mjs +33 -16
- package/dist/linkedin-search/index.mjs.map +1 -1
- package/dist/microsoft/conformance/calendar-cancel.d.mts +11 -0
- package/dist/microsoft/conformance/calendar-cancel.d.mts.map +1 -0
- package/dist/microsoft/conformance/calendar-cancel.mjs +103 -0
- package/dist/microsoft/conformance/calendar-cancel.mjs.map +1 -0
- package/dist/microsoft/conformance/calendar-create-event.d.mts +11 -0
- package/dist/microsoft/conformance/calendar-create-event.d.mts.map +1 -0
- package/dist/microsoft/conformance/calendar-create-event.mjs +121 -0
- package/dist/microsoft/conformance/calendar-create-event.mjs.map +1 -0
- package/dist/microsoft/conformance/calendar-list-range.d.mts +11 -0
- package/dist/microsoft/conformance/calendar-list-range.d.mts.map +1 -0
- package/dist/microsoft/conformance/calendar-list-range.mjs +39 -0
- package/dist/microsoft/conformance/calendar-list-range.mjs.map +1 -0
- package/dist/microsoft/conformance/calendar-timestamp-precision.d.mts +11 -0
- package/dist/microsoft/conformance/calendar-timestamp-precision.d.mts.map +1 -0
- package/dist/microsoft/conformance/calendar-timestamp-precision.mjs +56 -0
- package/dist/microsoft/conformance/calendar-timestamp-precision.mjs.map +1 -0
- package/dist/microsoft/conformance/calendar.d.mts +196 -0
- package/dist/microsoft/conformance/calendar.d.mts.map +1 -0
- package/dist/microsoft/conformance/calendar.mjs +216 -0
- package/dist/microsoft/conformance/calendar.mjs.map +1 -0
- package/dist/microsoft/conformance/cases.d.mts +123 -0
- package/dist/microsoft/conformance/cases.d.mts.map +1 -0
- package/dist/microsoft/conformance/cases.mjs +759 -0
- package/dist/microsoft/conformance/cases.mjs.map +1 -0
- package/dist/microsoft/conformance/index.d.mts +18 -0
- package/dist/microsoft/conformance/index.d.mts.map +1 -0
- package/dist/microsoft/conformance/index.mjs +31 -0
- package/dist/microsoft/conformance/index.mjs.map +1 -0
- package/dist/microsoft/conformance/onedrive-copy-monitor.d.mts +11 -0
- package/dist/microsoft/conformance/onedrive-copy-monitor.d.mts.map +1 -0
- package/dist/microsoft/conformance/onedrive-copy-monitor.mjs +122 -0
- package/dist/microsoft/conformance/onedrive-copy-monitor.mjs.map +1 -0
- package/dist/microsoft/conformance/onedrive-create-folder.d.mts +11 -0
- package/dist/microsoft/conformance/onedrive-create-folder.d.mts.map +1 -0
- package/dist/microsoft/conformance/onedrive-create-folder.mjs +79 -0
- package/dist/microsoft/conformance/onedrive-create-folder.mjs.map +1 -0
- package/dist/microsoft/conformance/outlook-attachment-content-id.d.mts +11 -0
- package/dist/microsoft/conformance/outlook-attachment-content-id.d.mts.map +1 -0
- package/dist/microsoft/conformance/outlook-attachment-content-id.mjs +50 -0
- package/dist/microsoft/conformance/outlook-attachment-content-id.mjs.map +1 -0
- package/dist/microsoft/conformance/outlook-attachments-listing.d.mts +11 -0
- package/dist/microsoft/conformance/outlook-attachments-listing.d.mts.map +1 -0
- package/dist/microsoft/conformance/outlook-attachments-listing.mjs +68 -0
- package/dist/microsoft/conformance/outlook-attachments-listing.mjs.map +1 -0
- package/dist/microsoft/conformance/outlook-concurrent-writes.d.mts +11 -0
- package/dist/microsoft/conformance/outlook-concurrent-writes.d.mts.map +1 -0
- package/dist/microsoft/conformance/outlook-concurrent-writes.mjs +103 -0
- package/dist/microsoft/conformance/outlook-concurrent-writes.mjs.map +1 -0
- package/dist/microsoft/conformance/outlook-immutable-id.d.mts +11 -0
- package/dist/microsoft/conformance/outlook-immutable-id.d.mts.map +1 -0
- package/dist/microsoft/conformance/outlook-immutable-id.mjs +103 -0
- package/dist/microsoft/conformance/outlook-immutable-id.mjs.map +1 -0
- package/dist/microsoft/conformance/outlook-paging-next-link.d.mts +11 -0
- package/dist/microsoft/conformance/outlook-paging-next-link.d.mts.map +1 -0
- package/dist/microsoft/conformance/outlook-paging-next-link.mjs +50 -0
- package/dist/microsoft/conformance/outlook-paging-next-link.mjs.map +1 -0
- package/dist/microsoft/conformance/seeds.d.mts +8 -0
- package/dist/microsoft/conformance/seeds.d.mts.map +1 -0
- package/dist/microsoft/conformance/seeds.mjs +22 -0
- package/dist/microsoft/conformance/seeds.mjs.map +1 -0
- package/dist/microsoft/download.d.mts +52 -0
- package/dist/microsoft/download.d.mts.map +1 -0
- package/dist/microsoft/download.mjs +227 -0
- package/dist/microsoft/download.mjs.map +1 -0
- package/dist/microsoft/drive.d.mts +165 -0
- package/dist/microsoft/drive.d.mts.map +1 -0
- package/dist/microsoft/drive.mjs +593 -0
- package/dist/microsoft/drive.mjs.map +1 -0
- package/dist/microsoft/index.d.mts +19 -0
- package/dist/microsoft/index.d.mts.map +1 -0
- package/dist/microsoft/index.mjs +27 -0
- package/dist/microsoft/index.mjs.map +1 -0
- package/dist/microsoft/mail-batch.d.mts +57 -0
- package/dist/microsoft/mail-batch.d.mts.map +1 -0
- package/dist/microsoft/mail-batch.mjs +102 -0
- package/dist/microsoft/mail-batch.mjs.map +1 -0
- package/dist/microsoft/mail-download.d.mts +25 -0
- package/dist/microsoft/mail-download.d.mts.map +1 -0
- package/dist/microsoft/mail-download.mjs +50 -0
- package/dist/microsoft/mail-download.mjs.map +1 -0
- package/dist/microsoft/mail-upload.d.mts +36 -0
- package/dist/microsoft/mail-upload.d.mts.map +1 -0
- package/dist/microsoft/mail-upload.mjs +205 -0
- package/dist/microsoft/mail-upload.mjs.map +1 -0
- package/dist/microsoft/mail.d.mts +523 -0
- package/dist/microsoft/mail.d.mts.map +1 -0
- package/dist/microsoft/mail.mjs +1969 -0
- package/dist/microsoft/mail.mjs.map +1 -0
- package/dist/microsoft/oauth.d.mts +78 -0
- package/dist/microsoft/oauth.d.mts.map +1 -0
- package/dist/microsoft/oauth.mjs +190 -0
- package/dist/microsoft/oauth.mjs.map +1 -0
- package/dist/microsoft/shared.d.mts +22 -0
- package/dist/microsoft/shared.d.mts.map +1 -0
- package/dist/microsoft/shared.mjs +76 -0
- package/dist/microsoft/shared.mjs.map +1 -0
- package/dist/microsoft/sites.d.mts +51 -0
- package/dist/microsoft/sites.d.mts.map +1 -0
- package/dist/microsoft/sites.mjs +204 -0
- package/dist/microsoft/sites.mjs.map +1 -0
- package/dist/microsoft/teams-download.d.mts +30 -0
- package/dist/microsoft/teams-download.d.mts.map +1 -0
- package/dist/microsoft/teams-download.mjs +56 -0
- package/dist/microsoft/teams-download.mjs.map +1 -0
- package/dist/microsoft/teams.d.mts +278 -0
- package/dist/microsoft/teams.d.mts.map +1 -0
- package/dist/microsoft/teams.mjs +993 -0
- package/dist/microsoft/teams.mjs.map +1 -0
- package/dist/microsoft/write.d.mts +35 -0
- package/dist/microsoft/write.d.mts.map +1 -0
- package/dist/microsoft/write.mjs +67 -0
- package/dist/microsoft/write.mjs.map +1 -0
- package/dist/notion/conformance/archive-in-trash.d.mts +12 -0
- package/dist/notion/conformance/archive-in-trash.d.mts.map +1 -0
- package/dist/notion/conformance/archive-in-trash.mjs +99 -0
- package/dist/notion/conformance/archive-in-trash.mjs.map +1 -0
- package/dist/notion/conformance/block-children-paging.d.mts +12 -0
- package/dist/notion/conformance/block-children-paging.d.mts.map +1 -0
- package/dist/notion/conformance/block-children-paging.mjs +86 -0
- package/dist/notion/conformance/block-children-paging.mjs.map +1 -0
- package/dist/notion/conformance/cases.d.mts +114 -0
- package/dist/notion/conformance/cases.d.mts.map +1 -0
- package/dist/notion/conformance/cases.mjs +670 -0
- package/dist/notion/conformance/cases.mjs.map +1 -0
- package/dist/notion/conformance/data-source-split.d.mts +13 -0
- package/dist/notion/conformance/data-source-split.d.mts.map +1 -0
- package/dist/notion/conformance/data-source-split.mjs +154 -0
- package/dist/notion/conformance/data-source-split.mjs.map +1 -0
- package/dist/notion/conformance/error-envelope.d.mts +12 -0
- package/dist/notion/conformance/error-envelope.d.mts.map +1 -0
- package/dist/notion/conformance/error-envelope.mjs +57 -0
- package/dist/notion/conformance/error-envelope.mjs.map +1 -0
- package/dist/notion/conformance/index.d.mts +15 -0
- package/dist/notion/conformance/index.d.mts.map +1 -0
- package/dist/notion/conformance/index.mjs +25 -0
- package/dist/notion/conformance/index.mjs.map +1 -0
- package/dist/notion/conformance/pinned-version.d.mts +12 -0
- package/dist/notion/conformance/pinned-version.d.mts.map +1 -0
- package/dist/notion/conformance/pinned-version.mjs +48 -0
- package/dist/notion/conformance/pinned-version.mjs.map +1 -0
- package/dist/notion/conformance/property-item-paging.d.mts +13 -0
- package/dist/notion/conformance/property-item-paging.d.mts.map +1 -0
- package/dist/notion/conformance/property-item-paging.mjs +133 -0
- package/dist/notion/conformance/property-item-paging.mjs.map +1 -0
- package/dist/notion/conformance/search-paging.d.mts +12 -0
- package/dist/notion/conformance/search-paging.d.mts.map +1 -0
- package/dist/notion/conformance/search-paging.mjs +108 -0
- package/dist/notion/conformance/search-paging.mjs.map +1 -0
- package/dist/notion/conformance/seeds.d.mts +9 -0
- package/dist/notion/conformance/seeds.d.mts.map +1 -0
- package/dist/notion/conformance/seeds.mjs +20 -0
- package/dist/notion/conformance/seeds.mjs.map +1 -0
- package/dist/notion/conformance/title-plain-text.d.mts +12 -0
- package/dist/notion/conformance/title-plain-text.d.mts.map +1 -0
- package/dist/notion/conformance/title-plain-text.mjs +77 -0
- package/dist/notion/conformance/title-plain-text.mjs.map +1 -0
- package/dist/notion/download.d.mts +28 -0
- package/dist/notion/download.d.mts.map +1 -0
- package/dist/notion/download.mjs +27 -0
- package/dist/notion/download.mjs.map +1 -0
- package/dist/notion/index.d.mts +75 -73
- package/dist/notion/index.d.mts.map +1 -1
- package/dist/notion/index.mjs +179 -83
- package/dist/notion/index.mjs.map +1 -1
- package/dist/portable-metadata.d.mts +35 -0
- package/dist/portable-metadata.d.mts.map +1 -0
- package/dist/portable-metadata.mjs +99 -0
- package/dist/portable-metadata.mjs.map +1 -0
- package/dist/r2-storage/conformance/backend.d.mts +143 -0
- package/dist/r2-storage/conformance/backend.d.mts.map +1 -0
- package/dist/r2-storage/conformance/backend.mjs +400 -0
- package/dist/r2-storage/conformance/backend.mjs.map +1 -0
- package/dist/r2-storage/conformance/cases.d.mts +96 -0
- package/dist/r2-storage/conformance/cases.d.mts.map +1 -0
- package/dist/r2-storage/conformance/cases.mjs +511 -0
- package/dist/r2-storage/conformance/cases.mjs.map +1 -0
- package/dist/r2-storage/conformance/create-if-absent.d.mts +8 -0
- package/dist/r2-storage/conformance/create-if-absent.d.mts.map +1 -0
- package/dist/r2-storage/conformance/create-if-absent.mjs +59 -0
- package/dist/r2-storage/conformance/create-if-absent.mjs.map +1 -0
- package/dist/r2-storage/conformance/get-expected-etag.d.mts +7 -0
- package/dist/r2-storage/conformance/get-expected-etag.d.mts.map +1 -0
- package/dist/r2-storage/conformance/get-expected-etag.mjs +54 -0
- package/dist/r2-storage/conformance/get-expected-etag.mjs.map +1 -0
- package/dist/r2-storage/conformance/get-max-bytes.d.mts +8 -0
- package/dist/r2-storage/conformance/get-max-bytes.d.mts.map +1 -0
- package/dist/r2-storage/conformance/get-max-bytes.mjs +37 -0
- package/dist/r2-storage/conformance/get-max-bytes.mjs.map +1 -0
- package/dist/r2-storage/conformance/get-missing.d.mts +7 -0
- package/dist/r2-storage/conformance/get-missing.d.mts.map +1 -0
- package/dist/r2-storage/conformance/get-missing.mjs +25 -0
- package/dist/r2-storage/conformance/get-missing.mjs.map +1 -0
- package/dist/r2-storage/conformance/index.d.mts +14 -0
- package/dist/r2-storage/conformance/index.d.mts.map +1 -0
- package/dist/r2-storage/conformance/index.mjs +22 -0
- package/dist/r2-storage/conformance/index.mjs.map +1 -0
- package/dist/r2-storage/conformance/presign-upload-url.d.mts +8 -0
- package/dist/r2-storage/conformance/presign-upload-url.d.mts.map +1 -0
- package/dist/r2-storage/conformance/presign-upload-url.mjs +24 -0
- package/dist/r2-storage/conformance/presign-upload-url.mjs.map +1 -0
- package/dist/r2-storage/conformance/seeds.d.mts +8 -0
- package/dist/r2-storage/conformance/seeds.d.mts.map +1 -0
- package/dist/r2-storage/conformance/seeds.mjs +15 -0
- package/dist/r2-storage/conformance/seeds.mjs.map +1 -0
- package/dist/r2-storage/conformance/synthetic.d.mts +20 -0
- package/dist/r2-storage/conformance/synthetic.d.mts.map +1 -0
- package/dist/r2-storage/conformance/synthetic.mjs +38 -0
- package/dist/r2-storage/conformance/synthetic.mjs.map +1 -0
- package/dist/r2-storage/conformance/update-if-match.d.mts +9 -0
- package/dist/r2-storage/conformance/update-if-match.d.mts.map +1 -0
- package/dist/r2-storage/conformance/update-if-match.mjs +78 -0
- package/dist/r2-storage/conformance/update-if-match.mjs.map +1 -0
- package/dist/r2-storage/files.d.mts +66 -0
- package/dist/r2-storage/files.d.mts.map +1 -0
- package/dist/r2-storage/files.mjs +66 -0
- package/dist/r2-storage/files.mjs.map +1 -0
- package/dist/r2-storage/index.d.mts +19 -21
- package/dist/r2-storage/index.d.mts.map +1 -1
- package/dist/r2-storage/index.mjs +15 -13
- package/dist/r2-storage/index.mjs.map +1 -1
- package/dist/result.d.mts +9 -10
- package/dist/result.d.mts.map +1 -1
- package/dist/result.mjs +17 -10
- package/dist/result.mjs.map +1 -1
- package/dist/telegram/conformance/cases.d.mts +90 -0
- package/dist/telegram/conformance/cases.d.mts.map +1 -0
- package/dist/telegram/conformance/cases.mjs +339 -0
- package/dist/telegram/conformance/cases.mjs.map +1 -0
- package/dist/telegram/conformance/error-envelope.d.mts +14 -0
- package/dist/telegram/conformance/error-envelope.d.mts.map +1 -0
- package/dist/telegram/conformance/error-envelope.mjs +57 -0
- package/dist/telegram/conformance/error-envelope.mjs.map +1 -0
- package/dist/telegram/conformance/get-file-path.d.mts +13 -0
- package/dist/telegram/conformance/get-file-path.d.mts.map +1 -0
- package/dist/telegram/conformance/get-file-path.mjs +52 -0
- package/dist/telegram/conformance/get-file-path.mjs.map +1 -0
- package/dist/telegram/conformance/index.d.mts +11 -0
- package/dist/telegram/conformance/index.d.mts.map +1 -0
- package/dist/telegram/conformance/index.mjs +17 -0
- package/dist/telegram/conformance/index.mjs.map +1 -0
- package/dist/telegram/conformance/seeds.d.mts +9 -0
- package/dist/telegram/conformance/seeds.d.mts.map +1 -0
- package/dist/telegram/conformance/seeds.mjs +15 -0
- package/dist/telegram/conformance/seeds.mjs.map +1 -0
- package/dist/telegram/conformance/send-message.d.mts +13 -0
- package/dist/telegram/conformance/send-message.d.mts.map +1 -0
- package/dist/telegram/conformance/send-message.mjs +58 -0
- package/dist/telegram/conformance/send-message.mjs.map +1 -0
- package/dist/telegram/conformance/validate-get-chat.d.mts +12 -0
- package/dist/telegram/conformance/validate-get-chat.d.mts.map +1 -0
- package/dist/telegram/conformance/validate-get-chat.mjs +45 -0
- package/dist/telegram/conformance/validate-get-chat.mjs.map +1 -0
- package/dist/telegram/download.d.mts +18 -0
- package/dist/telegram/download.d.mts.map +1 -0
- package/dist/telegram/download.mjs +43 -0
- package/dist/telegram/download.mjs.map +1 -0
- package/dist/telegram/index.d.mts +12 -17
- package/dist/telegram/index.d.mts.map +1 -1
- package/dist/telegram/index.mjs +4 -19
- package/dist/telegram/index.mjs.map +1 -1
- package/dist/telegram/shared.d.mts +10 -0
- package/dist/telegram/shared.d.mts.map +1 -0
- package/dist/telegram/shared.mjs +23 -0
- package/dist/telegram/shared.mjs.map +1 -0
- package/dist/todoist/conformance/cases.d.mts +132 -0
- package/dist/todoist/conformance/cases.d.mts.map +1 -0
- package/dist/todoist/conformance/cases.mjs +578 -0
- package/dist/todoist/conformance/cases.mjs.map +1 -0
- package/dist/todoist/conformance/due-dates.d.mts +12 -0
- package/dist/todoist/conformance/due-dates.d.mts.map +1 -0
- package/dist/todoist/conformance/due-dates.mjs +150 -0
- package/dist/todoist/conformance/due-dates.mjs.map +1 -0
- package/dist/todoist/conformance/index.d.mts +14 -0
- package/dist/todoist/conformance/index.d.mts.map +1 -0
- package/dist/todoist/conformance/index.mjs +23 -0
- package/dist/todoist/conformance/index.mjs.map +1 -0
- package/dist/todoist/conformance/not-found-envelope.d.mts +11 -0
- package/dist/todoist/conformance/not-found-envelope.d.mts.map +1 -0
- package/dist/todoist/conformance/not-found-envelope.mjs +38 -0
- package/dist/todoist/conformance/not-found-envelope.mjs.map +1 -0
- package/dist/todoist/conformance/project-delete.d.mts +13 -0
- package/dist/todoist/conformance/project-delete.d.mts.map +1 -0
- package/dist/todoist/conformance/project-delete.mjs +135 -0
- package/dist/todoist/conformance/project-delete.mjs.map +1 -0
- package/dist/todoist/conformance/project-parent-id.d.mts +12 -0
- package/dist/todoist/conformance/project-parent-id.d.mts.map +1 -0
- package/dist/todoist/conformance/project-parent-id.mjs +96 -0
- package/dist/todoist/conformance/project-parent-id.mjs.map +1 -0
- package/dist/todoist/conformance/seeds.d.mts +9 -0
- package/dist/todoist/conformance/seeds.d.mts.map +1 -0
- package/dist/todoist/conformance/seeds.mjs +16 -0
- package/dist/todoist/conformance/seeds.mjs.map +1 -0
- package/dist/todoist/conformance/task-labels.d.mts +11 -0
- package/dist/todoist/conformance/task-labels.d.mts.map +1 -0
- package/dist/todoist/conformance/task-labels.mjs +81 -0
- package/dist/todoist/conformance/task-labels.mjs.map +1 -0
- package/dist/todoist/conformance/task-lifecycle.d.mts +12 -0
- package/dist/todoist/conformance/task-lifecycle.d.mts.map +1 -0
- package/dist/todoist/conformance/task-lifecycle.mjs +162 -0
- package/dist/todoist/conformance/task-lifecycle.mjs.map +1 -0
- package/dist/todoist/conformance/tasks-paging.d.mts +12 -0
- package/dist/todoist/conformance/tasks-paging.d.mts.map +1 -0
- package/dist/todoist/conformance/tasks-paging.mjs +76 -0
- package/dist/todoist/conformance/tasks-paging.mjs.map +1 -0
- package/dist/todoist/files.d.mts +46 -0
- package/dist/todoist/files.d.mts.map +1 -0
- package/dist/todoist/files.mjs +145 -0
- package/dist/todoist/files.mjs.map +1 -0
- package/dist/todoist/index.d.mts +81 -55
- package/dist/todoist/index.d.mts.map +1 -1
- package/dist/todoist/index.mjs +281 -156
- package/dist/todoist/index.mjs.map +1 -1
- package/dist/todoist/shared.d.mts +10 -0
- package/dist/todoist/shared.d.mts.map +1 -0
- package/dist/todoist/shared.mjs +23 -0
- package/dist/todoist/shared.mjs.map +1 -0
- package/dist/transfer-internal.d.mts +42 -0
- package/dist/transfer-internal.d.mts.map +1 -0
- package/dist/transfer-internal.mjs +103 -0
- package/dist/transfer-internal.mjs.map +1 -0
- package/dist/unsubscribe.d.mts +36 -0
- package/dist/unsubscribe.d.mts.map +1 -0
- package/dist/unsubscribe.mjs +52 -0
- package/dist/unsubscribe.mjs.map +1 -0
- package/package.json +109 -5
- package/src/action.ts +108 -23
- package/src/afloat/conformance/fixtures.ts +122 -0
- package/src/afloat/conformance/index.ts +71 -0
- package/src/afloat/conformance/seeds.ts +67 -0
- package/src/afloat/conformance/target.ts +116 -0
- package/src/afloat/conformance/tools.ts +1089 -0
- package/src/afloat/conformance/wire.ts +260 -0
- package/src/afloat/index.ts +90 -0
- package/src/agent.ts +207 -45
- package/src/base64-internal.ts +22 -0
- package/src/binary-http.ts +49 -0
- package/src/binary-write-http.ts +73 -0
- package/src/config.ts +5 -8
- package/src/conformance/cleanup-reporter.ts +131 -0
- package/src/conformance/index.ts +459 -0
- package/src/conformance/owned-write.ts +225 -0
- package/src/credential.ts +49 -17
- package/src/dropbox/conformance/cases.ts +1267 -0
- package/src/dropbox/conformance/copy-move-metadata.ts +122 -0
- package/src/dropbox/conformance/create-folder-conflict.ts +73 -0
- package/src/dropbox/conformance/delete-then-not-found.ts +70 -0
- package/src/dropbox/conformance/index.ts +73 -0
- package/src/dropbox/conformance/list-folder-paging.ts +91 -0
- package/src/dropbox/conformance/not-found-envelope.ts +35 -0
- package/src/dropbox/conformance/path-lower-lookup.ts +63 -0
- package/src/dropbox/conformance/search-continue.ts +71 -0
- package/src/dropbox/conformance/seeds.ts +16 -0
- package/src/dropbox/conformance/upload-rev-precondition.ts +121 -0
- package/src/dropbox/download.ts +287 -0
- package/src/dropbox/index.ts +761 -0
- package/src/dropbox/shared.ts +94 -0
- package/src/dropbox/write.ts +119 -0
- package/src/email/conformance/acceptance-not-delivery.ts +24 -0
- package/src/email/conformance/backend.ts +295 -0
- package/src/email/conformance/cases.ts +1419 -0
- package/src/email/conformance/draft-drafts-discovery.ts +52 -0
- package/src/email/conformance/filtered-list-no-fallback.ts +17 -0
- package/src/email/conformance/index.ts +107 -0
- package/src/email/conformance/legacy-host-sent-copy.ts +33 -0
- package/src/email/conformance/list-and-get-headers.ts +40 -0
- package/src/email/conformance/move-destination-ids.ts +86 -0
- package/src/email/conformance/pop3-rejections.ts +36 -0
- package/src/email/conformance/seeds.ts +19 -0
- package/src/email/conformance/sent-copy-statuses.ts +66 -0
- package/src/email/conformance/set-read-and-flag.ts +49 -0
- package/src/email/conformance/synthetic.ts +133 -0
- package/src/email/conformance/trash-untrash-to-inbox.ts +78 -0
- package/src/email/index.ts +1992 -0
- package/src/email-batch.ts +139 -0
- package/src/error.ts +3 -1
- package/src/figma/index.ts +47 -27
- package/src/file-output.ts +78 -0
- package/src/file-transfer.ts +39 -0
- package/src/fortnox/articles.ts +335 -0
- package/src/fortnox/conformance/cases.ts +980 -0
- package/src/fortnox/conformance/customer-empty-string.ts +152 -0
- package/src/fortnox/conformance/index.ts +65 -0
- package/src/fortnox/conformance/invoice-list-populated.ts +38 -0
- package/src/fortnox/conformance/invoice-payment-filters.ts +71 -0
- package/src/fortnox/conformance/invoice-preview-pdf.ts +36 -0
- package/src/fortnox/conformance/invoice-row-discount.ts +270 -0
- package/src/fortnox/conformance/invoice-send-email.ts +54 -0
- package/src/fortnox/conformance/seeds.ts +16 -0
- package/src/fortnox/conformance/write-rejection.ts +61 -0
- package/src/fortnox/cost-centers.ts +197 -0
- package/src/fortnox/fields.ts +61 -0
- package/src/fortnox/files.ts +132 -0
- package/src/fortnox/inbox.ts +352 -0
- package/src/fortnox/index.ts +408 -0
- package/src/fortnox/oauth.ts +91 -0
- package/src/fortnox/offers.ts +552 -0
- package/src/fortnox/payments.ts +584 -0
- package/src/fortnox/prices.ts +380 -0
- package/src/fortnox/print-templates.ts +57 -0
- package/src/fortnox/profile.ts +34 -0
- package/src/fortnox/schemas.ts +469 -0
- package/src/fortnox/settings-registers.ts +712 -0
- package/src/fortnox/settings.ts +328 -0
- package/src/fortnox/shared.ts +304 -0
- package/src/fortnox/transfer.ts +68 -0
- package/src/fortnox/wire.ts +200 -0
- package/src/github/app-token.ts +375 -0
- package/src/github/attachments.ts +271 -0
- package/src/github/comments.ts +532 -0
- package/src/github/conformance/cases.ts +1090 -0
- package/src/github/conformance/comment-lifecycle.ts +78 -0
- package/src/github/conformance/file-contents.ts +56 -0
- package/src/github/conformance/index.ts +69 -0
- package/src/github/conformance/issue-labels.ts +98 -0
- package/src/github/conformance/issue-lifecycle.ts +88 -0
- package/src/github/conformance/labels-paging.ts +76 -0
- package/src/github/conformance/not-found-envelope.ts +39 -0
- package/src/github/conformance/seeds.ts +16 -0
- package/src/github/conformance/synthetic.ts +138 -0
- package/src/github/conformance/validation-envelope.ts +50 -0
- package/src/github/index.ts +61 -0
- package/src/github/issues.ts +876 -0
- package/src/github/pulls.ts +1260 -0
- package/src/github/repository.ts +643 -0
- package/src/github/shared.ts +635 -0
- package/src/github/structure.ts +699 -0
- package/src/google/calendar.ts +141 -31
- package/src/google/conformance/calendar-cases.ts +387 -0
- package/src/google/conformance/calendar-deleted-gone.ts +101 -0
- package/src/google/conformance/calendar-event-lifecycle.ts +99 -0
- package/src/google/conformance/calendar-list-range.ts +104 -0
- package/src/google/conformance/cases.ts +319 -0
- package/src/google/conformance/drive-cases.ts +296 -0
- package/src/google/conformance/drive-folder-lifecycle.ts +89 -0
- package/src/google/conformance/drive-get-file-fields.ts +47 -0
- package/src/google/conformance/drive-list-paging.ts +51 -0
- package/src/google/conformance/gmail-attachment.ts +80 -0
- package/src/google/conformance/gmail-cases.ts +1018 -0
- package/src/google/conformance/gmail-draft-lifecycle.ts +209 -0
- package/src/google/conformance/gmail-label-lifecycle.ts +79 -0
- package/src/google/conformance/gmail-list-paging.ts +58 -0
- package/src/google/conformance/gmail-list-threads-paging.ts +78 -0
- package/src/google/conformance/gmail-metadata-headers.ts +77 -0
- package/src/google/conformance/gmail-not-found-envelope.ts +30 -0
- package/src/google/conformance/gmail-send-practice.ts +90 -0
- package/src/google/conformance/gmail-trash-untrash.ts +62 -0
- package/src/google/conformance/index.ts +103 -0
- package/src/google/conformance/seeds.ts +24 -0
- package/src/google/conformance/shared.ts +426 -0
- package/src/google/conformance/synthetic.ts +378 -0
- package/src/google/drive-download.ts +221 -0
- package/src/google/drive.ts +751 -0
- package/src/google/gmail-download.ts +74 -0
- package/src/google/gmail-draft-mime.ts +348 -0
- package/src/google/gmail.ts +2709 -197
- package/src/google/index.ts +154 -2
- package/src/google/oauth.ts +128 -2
- package/src/google/shared.ts +159 -29
- package/src/http.ts +38 -21
- package/src/index.ts +50 -0
- package/src/integration.ts +16 -8
- package/src/kie/index.ts +457 -0
- package/src/linkedin-search/conformance/cases.ts +669 -0
- package/src/linkedin-search/conformance/email-lookup.ts +33 -0
- package/src/linkedin-search/conformance/enrich-layer-unauthorized.ts +45 -0
- package/src/linkedin-search/conformance/exa-unauthorized.ts +42 -0
- package/src/linkedin-search/conformance/index.ts +73 -0
- package/src/linkedin-search/conformance/num-results-limit.ts +97 -0
- package/src/linkedin-search/conformance/people-results.ts +62 -0
- package/src/linkedin-search/conformance/profile-not-found.ts +37 -0
- package/src/linkedin-search/conformance/profile.ts +38 -0
- package/src/linkedin-search/conformance/seeds.ts +13 -0
- package/src/linkedin-search/index.ts +83 -23
- package/src/microsoft/conformance/calendar-cancel.ts +112 -0
- package/src/microsoft/conformance/calendar-create-event.ts +131 -0
- package/src/microsoft/conformance/calendar-list-range.ts +40 -0
- package/src/microsoft/conformance/calendar-timestamp-precision.ts +59 -0
- package/src/microsoft/conformance/calendar.ts +351 -0
- package/src/microsoft/conformance/cases.ts +1390 -0
- package/src/microsoft/conformance/index.ts +86 -0
- package/src/microsoft/conformance/onedrive-copy-monitor.ts +149 -0
- package/src/microsoft/conformance/onedrive-create-folder.ts +92 -0
- package/src/microsoft/conformance/outlook-attachment-content-id.ts +57 -0
- package/src/microsoft/conformance/outlook-attachments-listing.ts +75 -0
- package/src/microsoft/conformance/outlook-concurrent-writes.ts +127 -0
- package/src/microsoft/conformance/outlook-immutable-id.ts +127 -0
- package/src/microsoft/conformance/outlook-paging-next-link.ts +57 -0
- package/src/microsoft/conformance/seeds.ts +20 -0
- package/src/microsoft/download.ts +379 -0
- package/src/microsoft/drive.ts +1064 -0
- package/src/microsoft/index.ts +338 -0
- package/src/microsoft/mail-batch.ts +186 -0
- package/src/microsoft/mail-download.ts +99 -0
- package/src/microsoft/mail-upload.ts +428 -0
- package/src/microsoft/mail.ts +3216 -0
- package/src/microsoft/oauth.ts +295 -0
- package/src/microsoft/shared.ts +162 -0
- package/src/microsoft/sites.ts +308 -0
- package/src/microsoft/teams-download.ts +89 -0
- package/src/microsoft/teams.ts +1382 -0
- package/src/microsoft/write.ts +136 -0
- package/src/notion/conformance/archive-in-trash.ts +95 -0
- package/src/notion/conformance/block-children-paging.ts +85 -0
- package/src/notion/conformance/cases.ts +1233 -0
- package/src/notion/conformance/data-source-split.ts +119 -0
- package/src/notion/conformance/error-envelope.ts +60 -0
- package/src/notion/conformance/index.ts +72 -0
- package/src/notion/conformance/pinned-version.ts +45 -0
- package/src/notion/conformance/property-item-paging.ts +120 -0
- package/src/notion/conformance/search-paging.ts +96 -0
- package/src/notion/conformance/seeds.ts +18 -0
- package/src/notion/conformance/title-plain-text.ts +74 -0
- package/src/notion/download.ts +63 -0
- package/src/notion/index.ts +300 -107
- package/src/portable-metadata.ts +165 -0
- package/src/r2-storage/conformance/backend.ts +669 -0
- package/src/r2-storage/conformance/cases.ts +823 -0
- package/src/r2-storage/conformance/create-if-absent.ts +56 -0
- package/src/r2-storage/conformance/get-expected-etag.ts +57 -0
- package/src/r2-storage/conformance/get-max-bytes.ts +46 -0
- package/src/r2-storage/conformance/get-missing.ts +21 -0
- package/src/r2-storage/conformance/index.ts +94 -0
- package/src/r2-storage/conformance/presign-upload-url.ts +25 -0
- package/src/r2-storage/conformance/seeds.ts +13 -0
- package/src/r2-storage/conformance/synthetic.ts +57 -0
- package/src/r2-storage/conformance/update-if-match.ts +73 -0
- package/src/r2-storage/files.ts +186 -0
- package/src/r2-storage/index.ts +49 -15
- package/src/result.ts +29 -5
- package/src/telegram/conformance/cases.ts +601 -0
- package/src/telegram/conformance/error-envelope.ts +54 -0
- package/src/telegram/conformance/get-file-path.ts +53 -0
- package/src/telegram/conformance/index.ts +55 -0
- package/src/telegram/conformance/seeds.ts +13 -0
- package/src/telegram/conformance/send-message.ts +54 -0
- package/src/telegram/conformance/validate-get-chat.ts +45 -0
- package/src/telegram/download.ts +83 -0
- package/src/telegram/index.ts +14 -24
- package/src/telegram/shared.ts +37 -0
- package/src/todoist/conformance/cases.ts +1067 -0
- package/src/todoist/conformance/due-dates.ts +150 -0
- package/src/todoist/conformance/index.ts +70 -0
- package/src/todoist/conformance/not-found-envelope.ts +38 -0
- package/src/todoist/conformance/project-delete.ts +123 -0
- package/src/todoist/conformance/project-parent-id.ts +85 -0
- package/src/todoist/conformance/seeds.ts +14 -0
- package/src/todoist/conformance/task-labels.ts +83 -0
- package/src/todoist/conformance/task-lifecycle.ts +142 -0
- package/src/todoist/conformance/tasks-paging.ts +82 -0
- package/src/todoist/files.ts +219 -0
- package/src/todoist/index.ts +384 -161
- package/src/todoist/shared.ts +37 -0
- package/src/transfer-internal.ts +225 -0
- package/src/unsubscribe.ts +96 -0
package/README.md
CHANGED
|
@@ -1,28 +1,52 @@
|
|
|
1
1
|
# @yolk-sdk/connectors
|
|
2
2
|
|
|
3
|
-
Effect-native connector primitives for hosts that bring their own auth, storage, and policy.
|
|
3
|
+
Effect-native connector primitives and reusable provider actions for hosts that bring their own auth, storage, and policy.
|
|
4
4
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
pnpm add @yolk-sdk/connectors@canary effect
|
|
8
|
+
pnpm add @yolk-sdk/connectors@canary @yolk-sdk/agent@canary effect@4.1.2
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
+
Running the experimental `@yolk-sdk/connectors/*/conformance` cases? Also add `@yolk-sdk/conformance@canary` (usually as a dev dependency); the examples import `@yolk-sdk/conformance/*` subpaths directly.
|
|
12
|
+
|
|
11
13
|
Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
|
|
14
|
+
Use the SDK's matching Effect version (`4.1.2`) in host code.
|
|
15
|
+
Published package metadata requires Node.js 22+.
|
|
12
16
|
|
|
13
17
|
## Subpaths
|
|
14
18
|
|
|
15
|
-
| Subpath
|
|
16
|
-
|
|
|
17
|
-
| `@yolk-sdk/connectors`
|
|
18
|
-
| `@yolk-sdk/connectors/agent`
|
|
19
|
-
| `@yolk-sdk/connectors/
|
|
20
|
-
| `@yolk-sdk/connectors/
|
|
21
|
-
| `@yolk-sdk/connectors/
|
|
22
|
-
| `@yolk-sdk/connectors/
|
|
23
|
-
| `@yolk-sdk/connectors/
|
|
24
|
-
| `@yolk-sdk/connectors/
|
|
25
|
-
| `@yolk-sdk/connectors/
|
|
19
|
+
| Subpath | Purpose |
|
|
20
|
+
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
21
|
+
| `@yolk-sdk/connectors` | Core connector/action/integration/credential primitives plus binary HTTP ports and file-transfer types |
|
|
22
|
+
| `@yolk-sdk/connectors/agent` | Adapter from connector actions to `@yolk-sdk/agent/tools` modules |
|
|
23
|
+
| `@yolk-sdk/connectors/afloat` | Afloat remote MCP auth action, API-key slot, endpoint, and protocol version |
|
|
24
|
+
| `@yolk-sdk/connectors/afloat/conformance` | Experimental Afloat target, seeds, and derived fixtures for the `@yolk-sdk/mcp/conformance` cases |
|
|
25
|
+
| `@yolk-sdk/connectors/conformance` | Experimental, conformance/testing only: Effect `HttpClient` bridges, a static resolver, and a cleanup reporter |
|
|
26
|
+
| `@yolk-sdk/connectors/dropbox` | Dropbox metadata, search, file-management actions, OAuth slots, and host-only download plus create/update |
|
|
27
|
+
| `@yolk-sdk/connectors/dropbox/conformance` | Experimental Dropbox conformance cases, seed config, and synthetic replay fixtures |
|
|
28
|
+
| `@yolk-sdk/connectors/email` | Portable IMAP reads/drafts/message state/labels, POP3 reads, and SMTP submission through a host email port |
|
|
29
|
+
| `@yolk-sdk/connectors/email/conformance` | Experimental email port conformance cases, `PortFixture` replay, seeds, and a plain-JSON `EmailClient` bridge |
|
|
30
|
+
| `@yolk-sdk/connectors/figma` | Figma remote MCP auth action and OAuth constants |
|
|
31
|
+
| `@yolk-sdk/connectors/fortnox` | Company, customer, invoice, supplier, supplier-invoice, article, price, cost-center, payment, offer, print, inbox, settings, profile actions |
|
|
32
|
+
| `@yolk-sdk/connectors/fortnox/conformance` | Experimental Fortnox conformance cases, seed config, and synthetic replay fixtures |
|
|
33
|
+
| `@yolk-sdk/connectors/github` | Repo-scoped GitHub issue/PR/repository actions plus host-only App tokens and attachment upload |
|
|
34
|
+
| `@yolk-sdk/connectors/github/conformance` | Experimental GitHub conformance cases, seed config, and synthetic replay fixtures |
|
|
35
|
+
| `@yolk-sdk/connectors/google` | Gmail, Calendar, and Drive actions plus Google OAuth slot constants |
|
|
36
|
+
| `@yolk-sdk/connectors/google/conformance` | Experimental Gmail, Calendar, and Drive conformance cases, seed config, and synthetic replay fixtures |
|
|
37
|
+
| `@yolk-sdk/connectors/kie` | Kie image/video generation task submit (GPT Image 2, Wan 2.7) and task status actions, `KieApiKeySlot` (`kie.api_key`) |
|
|
38
|
+
| `@yolk-sdk/connectors/linkedin-search` | Exa people search and Enrich Layer profile/email actions |
|
|
39
|
+
| `@yolk-sdk/connectors/linkedin-search/conformance` | Experimental LinkedIn search (Exa, Enrich Layer) conformance cases, seed config, and synthetic replay fixtures |
|
|
40
|
+
| `@yolk-sdk/connectors/microsoft` | Outlook/OneDrive/SharePoint/Teams Graph actions, shared OAuth slots, host-only file and transcript download, upload, draft attachments |
|
|
41
|
+
| `@yolk-sdk/connectors/microsoft/conformance` | Experimental Microsoft Graph conformance cases, seed config, and synthetic replay fixtures |
|
|
42
|
+
| `@yolk-sdk/connectors/notion` | Notion search/page/block/database/data-source/comment/user actions and API token slot |
|
|
43
|
+
| `@yolk-sdk/connectors/notion/conformance` | Experimental Notion conformance cases, seed config, and synthetic replay fixtures |
|
|
44
|
+
| `@yolk-sdk/connectors/r2-storage` | Cloudflare R2 upload URL action plus host-only `R2ObjectClient` get/create/update |
|
|
45
|
+
| `@yolk-sdk/connectors/r2-storage/conformance` | Experimental R2 port conformance cases, seed config, synthetic port fixtures, and a plain-JSON bridge |
|
|
46
|
+
| `@yolk-sdk/connectors/telegram` | Telegram bot send/validate actions |
|
|
47
|
+
| `@yolk-sdk/connectors/telegram/conformance` | Experimental Telegram conformance cases, seed config, and synthetic replay fixtures |
|
|
48
|
+
| `@yolk-sdk/connectors/todoist` | Todoist project/task/label/comment actions and API token slot constants |
|
|
49
|
+
| `@yolk-sdk/connectors/todoist/conformance` | Experimental Todoist conformance cases, seed config, and synthetic replay fixtures |
|
|
26
50
|
|
|
27
51
|
## Imports
|
|
28
52
|
|
|
@@ -41,14 +65,52 @@ import { GoogleConnector } from '@yolk-sdk/connectors/google'
|
|
|
41
65
|
- **CredentialBinding**: integration slot-to-host-credential-ref mapping.
|
|
42
66
|
- **CredentialResolver**: host Effect service that resolves refs at runtime.
|
|
43
67
|
- **ConnectorHttpClient**: host-provided HTTP port used by provider actions.
|
|
68
|
+
- **ConnectorBinaryHttpClient** / **ConnectorBinaryWriteHttpClient**: optional host-provided GET/write byte ports used by host-only file helpers.
|
|
69
|
+
- **R2ObjectClient**: host-provided conditional object port for R2 get/create/update.
|
|
70
|
+
- **ConnectorFileTransferBudget**: host-owned streamed byte/metadata/error limits for those helpers.
|
|
71
|
+
- **EmailClient**: host-provided IMAP, POP3, and SMTP transport port used by generic email actions.
|
|
72
|
+
- **fileOutput**: optional on an action whose output carries file bytes (ADR 0009): a byte-free
|
|
73
|
+
`schema` and `split` into that value plus `ConnectorActionFile`s (`connectorActionFile`, with
|
|
74
|
+
`sniffBase64MimeType` for common types). The agent tool declares `{ value, files }` and returns
|
|
75
|
+
the bytes as file fields that tool resolution captures into `FileRef`s, or `FileUnavailable`
|
|
76
|
+
(`{ unavailable, name, mimeType }`) when no file store is configured, the file is too large or
|
|
77
|
+
storing failed (ADR 0013), so scripts check `'unavailable' in file` before reading
|
|
78
|
+
`result.files[0].fileId`; `connector.invoke` keeps
|
|
79
|
+
the full output. `gmail.get_attachment`, `outlook.get_attachment` and `email.get_attachment`
|
|
80
|
+
declare it.
|
|
81
|
+
|
|
82
|
+
`makeConnectorToolModule` uses the connector `description` as the module description (override
|
|
83
|
+
with `description`) and returns each action result as the JSON encoding of its `outputSchema`
|
|
84
|
+
(`Chunk`s become arrays, dates ISO strings) in both `structuredContent` and the text. `fileOutput`
|
|
85
|
+
actions declare and return `{ value, files }` instead: `value` is the encoded byte-free output,
|
|
86
|
+
`files` its file fields (`FileRef` or `FileUnavailable`), which the text shows as file labels. Fields the
|
|
87
|
+
output schema does not declare are not returned; a value that does not encode fails the call with
|
|
88
|
+
an `execution` `ToolError`, and provider failures carry the JSON-encoded `ProviderFailure` as
|
|
89
|
+
`structuredContent`. Agent tools decode arguments like `makeTool`: `null` optionals are absent and
|
|
90
|
+
unknown keys are model-visible validation errors (`execute`/`invoke` and `executeTyped` are
|
|
91
|
+
unchanged).
|
|
92
|
+
|
|
93
|
+
## Portable metadata
|
|
94
|
+
|
|
95
|
+
`ConnectorIntegration.metadata` and `CredentialBinding.metadata` use the exported
|
|
96
|
+
`PortableMetadata` schema. Omission stays absent. Decode/make admit a snapshot of plain JSON-object
|
|
97
|
+
data: finite primitives, dense ordinary arrays, and plain/null-prototype objects. Objects are copied
|
|
98
|
+
onto null prototypes, own `__proto__`/`constructor` keys survive, and DAG aliases share a copied node.
|
|
99
|
+
Snapshots are not frozen and do not retain input identity. Cycles, nonfinite/undefined/function
|
|
100
|
+
values, exotic prototypes (including Date/Map/classes), hidden/symbol keys, and accessors fail;
|
|
101
|
+
accessors are not invoked. Proxy reflection traps are not covered by a side-effect guarantee.
|
|
102
|
+
|
|
103
|
+
Migrate annotations to explicit JSON data before constructing integrations/bindings; serialize Dates
|
|
104
|
+
to strings and Maps to the intended data shape yourself. Integration `config`, credential secrets,
|
|
105
|
+
error `underlying`, and host database contracts are unchanged.
|
|
44
106
|
|
|
45
107
|
## HTTP port
|
|
46
108
|
|
|
47
|
-
|
|
109
|
+
The root export includes connector HTTP infrastructure, not a connector. It defines the typed HTTP request/response model, the `ConnectorHttpClient` Effect service, and JSON response decoding helpers.
|
|
48
110
|
|
|
49
111
|
Provider connectors build `ConnectorHttpRequest` values; hosts execute them by providing a `ConnectorHttpClient` layer. This keeps connector packages portable and avoids bundling `fetch`, Node HTTP clients, or app-specific networking policy.
|
|
50
112
|
|
|
51
|
-
Host adapters must preserve connector headers and body content type. Several provider actions send JSON and rely on `content-type: application/json` reaching the upstream API unchanged.
|
|
113
|
+
Host adapters must preserve connector headers and body content type. Several provider actions send JSON and rely on `content-type: application/json` reaching the upstream API unchanged. When a request sets `redirect: 'manual'` or `credentials: 'omit'`, adapters must not follow redirects and must not add cookie jars or ambient credentials. These request policies are security boundaries for capability URLs such as OneDrive copy monitors; ignoring them can leak credentials or bypass connector URL validation.
|
|
52
114
|
|
|
53
115
|
## Example
|
|
54
116
|
|
|
@@ -123,14 +185,241 @@ const program = Todoist.invoke({
|
|
|
123
185
|
}).pipe(Effect.provide(CredentialResolverLive))
|
|
124
186
|
```
|
|
125
187
|
|
|
188
|
+
`defineAction` also returns an additive typed entrypoint, `executeTyped`, alongside the dynamic
|
|
189
|
+
`execute` used by `invoke` and the agent adapter. It preserves `InputSchema.Type` and the output
|
|
190
|
+
type for direct host callers. It validates **decoded** input with `Schema.toType(inputSchema)`,
|
|
191
|
+
without replaying wire transformations. For example, a `NumberFromString` field accepts a number
|
|
192
|
+
through `executeTyped` and a string through dynamic `execute`. Implementations still own validation
|
|
193
|
+
of external output data; the generic executor does not automatically decode `outputSchema`.
|
|
194
|
+
|
|
195
|
+
Fragment using the action and integration above:
|
|
196
|
+
|
|
197
|
+
```ts
|
|
198
|
+
const typed = listTasks.executeTyped({ integration, input: {} })
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
## Generic email connector
|
|
202
|
+
|
|
203
|
+
```ts
|
|
204
|
+
import { makeCredentialBinding, makeIntegration } from '@yolk-sdk/connectors'
|
|
205
|
+
import {
|
|
206
|
+
EmailConnector,
|
|
207
|
+
EmailIncomingCredentialSlot,
|
|
208
|
+
EmailSmtpCredentialSlot
|
|
209
|
+
} from '@yolk-sdk/connectors/email'
|
|
210
|
+
|
|
211
|
+
const integration = makeIntegration({
|
|
212
|
+
connectorId: 'email',
|
|
213
|
+
config: {
|
|
214
|
+
incomingProtocol: 'imap',
|
|
215
|
+
incomingHost: 'imap.example.com',
|
|
216
|
+
smtpHost: 'smtp.example.com'
|
|
217
|
+
},
|
|
218
|
+
credentialBindings: [
|
|
219
|
+
makeCredentialBinding({
|
|
220
|
+
slotId: EmailIncomingCredentialSlot.id,
|
|
221
|
+
credentialRef: 'incoming-email-credential'
|
|
222
|
+
}),
|
|
223
|
+
makeCredentialBinding({
|
|
224
|
+
slotId: EmailSmtpCredentialSlot.id,
|
|
225
|
+
credentialRef: 'smtp-email-credential'
|
|
226
|
+
})
|
|
227
|
+
]
|
|
228
|
+
})
|
|
229
|
+
|
|
230
|
+
const program = EmailConnector.invoke({
|
|
231
|
+
integration,
|
|
232
|
+
action: 'email.list_messages',
|
|
233
|
+
input: { limit: 25 }
|
|
234
|
+
})
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
Provide `CredentialResolver` and `EmailClient` layers. The package never imports socket, TLS, MIME,
|
|
238
|
+
IMAP, POP3, or SMTP libraries. Incoming config defaults to IMAP with TLS (`993`); POP3 with TLS
|
|
239
|
+
defaults to `995`. SMTP defaults to STARTTLS on `587`, while explicit SMTP TLS defaults to `465`.
|
|
240
|
+
Ports accept integers or numeric strings. A POP3 action rejects `folder`; use IMAP for folder-aware
|
|
241
|
+
reads. Incoming and SMTP bindings are separate, but both may point to the same host credential ref.
|
|
242
|
+
Both slots require `UsernamePasswordCredential`; provider-specific OAuth remains available through
|
|
243
|
+
the Google and Microsoft connectors.
|
|
244
|
+
|
|
245
|
+
The common action set includes list/get/attachment/draft/send, the existing single-message IMAP
|
|
246
|
+
mutations, batch variants (`email.batch_set_read`, `email.batch_set_flag`, `email.batch_move`,
|
|
247
|
+
`email.batch_trash`, `email.batch_untrash`, `email.batch_modify_labels`), and the separate destructive
|
|
248
|
+
`email.delete_permanently` action.
|
|
249
|
+
Draft creation requires IMAP and uses the incoming
|
|
250
|
+
credential. An optional
|
|
251
|
+
`folder` selects the target mailbox; when omitted, the host adapter discovers a mailbox advertised
|
|
252
|
+
with `\Drafts` by the IMAP SPECIAL-USE extension and may fall back to `Drafts`. Drafts may omit
|
|
253
|
+
recipients.
|
|
254
|
+
The result reports `{ saved: true, folder, draftId? }` because IMAP servers without UIDPLUS may not
|
|
255
|
+
return an `APPENDUID`. `draftId`, when present, is an opaque adapter identifier; UIDPLUS adapters
|
|
256
|
+
must encode both UIDVALIDITY and UID rather than exposing a bare UID. The host adapter generates MIME
|
|
257
|
+
and performs `APPEND` with the `\Draft` flag.
|
|
258
|
+
|
|
259
|
+
Message list/get outputs expose normalized addresses, text/HTML bodies, attachment metadata, and
|
|
260
|
+
optional `isRead` / `isFlagged` booleans; omission means unavailable or unknown and remains backward
|
|
261
|
+
compatible. `email.list_messages` accepts optional `isRead` / `isFlagged` filters. Filtered IMAP
|
|
262
|
+
requests use optional `EmailClient.listMessagesFiltered` and never silently fall back to legacy
|
|
263
|
+
`listMessages`; POP3 filters fail before credential resolution. Successful list output is
|
|
264
|
+
schema-validated. Outputs never contain raw MIME. `email.get_message` additionally requires
|
|
265
|
+
`headers` name/value pairs (including
|
|
266
|
+
`List-Unsubscribe` when the mail carries it); hosts fetch them via IMAP `BODY.PEEK[HEADER]` or
|
|
267
|
+
POP3 `TOP` without marking the message read. Successful host output is schema-validated, so a
|
|
268
|
+
missing `headers` array fails. List summaries carry no headers. The package root exports the pure
|
|
269
|
+
`parseUnsubscribeMethods` helper for `List-Unsubscribe` discovery; see the [unsubscribe recipe](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/integrations/connectors.mdx#unsubscribe-from-mailing-lists-and-report-spam). When `EmailAttachmentMetadata.id` is present, pass it with the parent message ID to
|
|
270
|
+
`email.get_attachment`. The host returns decoded file bytes—not MIME transfer-encoded text—as
|
|
271
|
+
base64 in `contentBase64`; decoded `size` is a non-negative integer. Existing `EmailClient`
|
|
272
|
+
implementations may omit the optional `getAttachment` method; invoking the action then fails with a
|
|
273
|
+
typed validation error. Successful host output is schema-validated at the connector boundary before
|
|
274
|
+
it is returned. Hosts that implement it own MIME parsing, base64 encoding, size policy,
|
|
275
|
+
storage, and content scanning. As an agent tool the action resolves to `{ value, files }`
|
|
276
|
+
instead of base64: `value` is the metadata output, `files` the attachment as a `FileRef` (or
|
|
277
|
+
`FileUnavailable` when it was not stored).
|
|
278
|
+
IMAP adapters should fetch parts without marking messages read when supported. POP3 has no standard
|
|
279
|
+
partial-part fetch, so adapters may retrieve the whole stable UIDL-addressed message before
|
|
280
|
+
extracting the part. POP3 rejects `folder` for attachment retrieval just as it does for list/get.
|
|
281
|
+
List `id` values are opaque adapter identifiers that callers pass unchanged to `email.get_message`;
|
|
282
|
+
POP3 adapters must use UIDL or another stable mapping, never transient message sequence numbers. When IMAP `folder` is omitted, adapters use `INBOX`; POP3 uses its single mailbox.
|
|
283
|
+
Adapters return deterministic newest-first pages. Cursors are opaque, scoped to the integration,
|
|
284
|
+
protocol, folder, and ordering, and may fail after mailbox changes. Send success returns
|
|
285
|
+
`{ accepted: true, submissionId?, sentCopy }`, which means the SMTP server accepted submission,
|
|
286
|
+
not that the message was delivered. `email.send_message` accepts optional `saveToSentItems`
|
|
287
|
+
(default: save when possible) and `sentFolder`. When saving is requested and the incoming
|
|
288
|
+
account uses IMAP, the connector resolves the IMAP connection plus the separate incoming
|
|
289
|
+
credential before SMTP invocation and passes them as `sentCopy` with the SMTP request, so the
|
|
290
|
+
host can render once, submit the same bytes, and append the Sent copy without resubmission.
|
|
291
|
+
The host owns all APPEND mechanics and reports `sentCopy.status` as `saved | failed | skipped |
|
|
292
|
+
unsupported` with the storage `folder` when known. `failed` after acceptance never means the
|
|
293
|
+
message was not sent: do not resend. `skipped` means saving was disabled; `unsupported` means
|
|
294
|
+
saving was requested but unavailable (POP3, missing IMAP incoming, or a legacy host that omits
|
|
295
|
+
`sentCopy`, which the action synthesizes rather than implying `saved`).
|
|
296
|
+
|
|
297
|
+
### Read state, trash, and move (IMAP only)
|
|
298
|
+
|
|
299
|
+
| Action | Input | Host method | Access |
|
|
300
|
+
| --------------------- | --------------------------------------------------- | -------------------------- | ------------- |
|
|
301
|
+
| `email.set_read` | `{ messageId, isRead, folder? }` | `EmailClient.setRead` | `write` |
|
|
302
|
+
| `email.set_flag` | `{ messageId, isFlagged, folder? }` | `EmailClient.setFlag` | `write` |
|
|
303
|
+
| `email.trash` | `{ messageId, folder?, trashFolder? }` | `EmailClient.trash` | `destructive` |
|
|
304
|
+
| `email.untrash` | `{ messageId, folder?, destinationFolder? }` | `EmailClient.untrash` | `write` |
|
|
305
|
+
| `email.modify_labels` | `{ messageId, folder?, addLabels?, removeLabels? }` | `EmailClient.modifyLabels` | `write` |
|
|
306
|
+
| `email.move` | `{ messageId, folder?, destinationFolder }` | `EmailClient.move` | `write` |
|
|
307
|
+
|
|
308
|
+
Batch inputs replace only the identifier field with `messageIds`: 1-100 unique, nonempty IDs, one
|
|
309
|
+
source folder, and the same operation-specific payload/defaults as the single-message action. They
|
|
310
|
+
use optional `EmailClient.batchSetRead`, `batchSetFlag`, `batchMove`, `batchTrash`, `batchUntrash`,
|
|
311
|
+
and `batchModifyLabels` methods. `email.delete_permanently` takes `{ messageIds, folder? }`, defaults
|
|
312
|
+
`folder` to `INBOX`, uses optional `EmailClient.deletePermanently`, and is destructive. Missing
|
|
313
|
+
optional methods fail clearly; old adapters remain valid.
|
|
314
|
+
|
|
315
|
+
Every successful batch/delete output contains one result for every requested ID, preserves
|
|
316
|
+
`messageIds` input order, uses status `succeeded | failed | unknown | not_attempted`, includes an
|
|
317
|
+
optional sanitized code, and has exact summary counts. Every succeeded result from
|
|
318
|
+
`email.batch_move`, `email.batch_trash`, or
|
|
319
|
+
`email.batch_untrash` must include destination `folder`; only `movedMessageId` is optional, and
|
|
320
|
+
only when the adapter knows the destination UIDVALIDITY/UID mapping. The connector validates the
|
|
321
|
+
schema, requested-ID coverage, and counts. Hosts must never return raw provider errors.
|
|
322
|
+
|
|
323
|
+
Permanent deletion means removing exactly the identified UID-scoped messages from the selected
|
|
324
|
+
folder. Hosts must never use blanket `EXPUNGE`; approval/authorization remain downstream host
|
|
325
|
+
policy. Success does not promise erasure from backups, provider retention, journaling, or compliance
|
|
326
|
+
systems.
|
|
327
|
+
|
|
328
|
+
Set `isRead: true` to mark read, or `false` to mark unread. Set `isFlagged: true` to star for
|
|
329
|
+
follow-up via `\Flagged`, or `false` to unstar. These actions use the incoming
|
|
330
|
+
credential and require IMAP; POP3 is rejected before credential resolution or adapter calls.
|
|
331
|
+
SMTP is submission-only. These host methods are optional for compatibility: old adapters
|
|
332
|
+
continue working, but calling an unsupported action fails with a typed validation error.
|
|
333
|
+
Successful host output is schema-validated; provider failures pass through unchanged.
|
|
334
|
+
|
|
335
|
+
Hosts implement `setRead` using UID-addressed `STORE` to add/remove only `\Seen`, preserving
|
|
336
|
+
other flags. It returns `EmailSetReadOutput` (`{ messageId, isRead }`) after the server confirms
|
|
337
|
+
success. Set-read and trash source `folder` default to `INBOX`.
|
|
338
|
+
|
|
339
|
+
For trash, the adapter uses explicit `trashFolder` or discovers a `\Trash` SPECIAL-USE mailbox;
|
|
340
|
+
any fallback is host-configured, not a guessed folder or permanent deletion. For untrash, `folder`
|
|
341
|
+
selects the source trash mailbox; when omitted the adapter discovers it using the same policy.
|
|
342
|
+
The destination defaults to `INBOX`, or uses explicit `destinationFolder`. This does **not** restore
|
|
343
|
+
the original folder automatically. Hosts must reject missing/ambiguous trash discovery and unsafe
|
|
344
|
+
moves (including identical source/destination folders).
|
|
345
|
+
|
|
346
|
+
Use UID `MOVE` where supported, or a safe per-message copy/delete fallback. Never use a blanket
|
|
347
|
+
`EXPUNGE` that can delete unrelated messages, or treat setting `\Deleted` alone as a trash move.
|
|
348
|
+
If a safe move is unavailable, return a failure. Trash/untrash return `EmailMoveMessageOutput`
|
|
349
|
+
(`{ moved: true, folder, messageId? }`). `folder` is the destination; `messageId`, when known, is the
|
|
350
|
+
**new** opaque identifier there. UIDPLUS mappings must encode destination UIDVALIDITY and UID.
|
|
351
|
+
If no reliable mapping is available, omit `messageId` and re-list the destination; never reuse a
|
|
352
|
+
stale source UID. Hosts own safe retry/reconciliation after partially completed moves.
|
|
353
|
+
|
|
354
|
+
`email.move` takes `{ messageId, folder?, destinationFolder }` with a required destination and
|
|
355
|
+
returns `EmailMoveMessageOutput` with the destination folder and the new message ID when the host
|
|
356
|
+
can map it. Like the other mutations it requires IMAP, defaults `folder` to `INBOX`, rejects an
|
|
357
|
+
identical source/destination before dispatch, and fails with a typed validation error when the
|
|
358
|
+
optional `EmailClient.move` method is missing. Hosts move with UID `MOVE` (RFC 6851) when the
|
|
359
|
+
server advertises it, otherwise `COPY` plus flagging `\Deleted` and expunging only the moved UID;
|
|
360
|
+
they preserve flags and keywords, never blanket-expunge, and own partial-move reconciliation.
|
|
361
|
+
Destination UIDs differ from source UIDs, so callers must use the returned ID for subsequent
|
|
362
|
+
operations or re-list the destination. Hosts that resolve agent-declared access should treat moves
|
|
363
|
+
into `\Trash`-advertised mailboxes as destructive, matching `email.trash`.
|
|
364
|
+
|
|
365
|
+
### Labels (IMAP keywords only)
|
|
366
|
+
|
|
367
|
+
`email.modify_labels` takes `{ messageId, folder?, addLabels?, removeLabels? }` (at least one
|
|
368
|
+
of the two label lists) and returns `{ messageId, labels }` with the resulting keyword set as an Effect `Chunk`.
|
|
369
|
+
Hosts return `Chunk.fromIterable(keywords)`; message list/get discovery uses optional arrays.
|
|
370
|
+
Like the other mutations it uses the incoming credential, requires IMAP, defaults `folder` to
|
|
371
|
+
`INBOX`, and fails with a typed validation error when the optional `EmailClient.modifyLabels`
|
|
372
|
+
method is missing. POP3 and SMTP cannot persist labels: POP3 is rejected before credential
|
|
373
|
+
resolution, and SMTP is submission-only.
|
|
374
|
+
|
|
375
|
+
Labels are IMAP keywords only, never system flags. The connector schema-validates every
|
|
376
|
+
`addLabels`/`removeLabels` entry as an RFC 3501 `atom` (ASCII printable except `(`, `)`, `{`,
|
|
377
|
+
space, CTLs, `%`, `*`, `"`, `\`, `]`), so `\Seen` and other backslash flags, whitespace,
|
|
378
|
+
control characters, and atom specials fail before dispatch. Message list/get outputs may carry
|
|
379
|
+
an optional `labels` array for host discovery.
|
|
380
|
+
|
|
381
|
+
There is no standalone create/delete label catalog in IMAP: keywords implicitly exist through
|
|
382
|
+
message assignment, so hosts assign them directly and remove usage by removing a keyword from
|
|
383
|
+
messages. Hosts implement `modifyLabels` with UID-addressed `STORE` (`+FLAGS.SILENT` for
|
|
384
|
+
additions, `-FLAGS.SILENT` for removals), preserving all other keywords and system flags rather
|
|
385
|
+
than overwriting the whole flags list. Hosts check `PERMANENTFLAGS` first and return a failure
|
|
386
|
+
for unsupported keywords; a keyword listed in both inputs is removed.
|
|
387
|
+
|
|
388
|
+
### Email conformance cases (experimental)
|
|
389
|
+
|
|
390
|
+
`@yolk-sdk/connectors/email/conformance` exports ten port-level conformance cases for
|
|
391
|
+
`@yolk-sdk/conformance/runner` (`emailConformanceCases`), their synthetic `PortFixture`s
|
|
392
|
+
(`emailConformanceFixtures`; no `observed`, so `unverified`), and the seeds they replay with
|
|
393
|
+
(`emailConformanceFixtureSeeds`). Yolk never speaks IMAP, POP3, or SMTP: each case runs the real
|
|
394
|
+
email actions over the host `EmailClient` plus `CredentialResolver` and `EmailConformanceConfig`
|
|
395
|
+
(practice-mailbox seeds; a missing seed fails with a `precondition:` mismatch before any port
|
|
396
|
+
call). They cover required `get_message` headers without marking a message read, filtered listing
|
|
397
|
+
without `listMessages` fallback, `\Drafts` discovery, `set_read`/`set_flag`, trash and untrash to
|
|
398
|
+
INBOX, moves returning destination ids (the stale source id must answer the `message_not_found`
|
|
399
|
+
failure code, `emailMessageNotFoundCode`), POP3 rejections of every mutation action, Sent-copy statuses (including the legacy
|
|
400
|
+
`unsupported`/`skipped` synthesis), and SMTP acceptance that is not delivery. Case table:
|
|
401
|
+
[Email conformance guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/connectors/email.mdx#conformance-cases).
|
|
402
|
+
|
|
403
|
+
The subpath also ships a small bridge for conformance and tests only: `emailClientLayerFromBackend`
|
|
404
|
+
(and `emailClientFromBackend`) turn any plain-JSON backend `{ call(method, request) }` into the
|
|
405
|
+
`EmailClient` port. Requests reach the backend as plain JSON without credential fields; a
|
|
406
|
+
`response` is decoded with the method's output schema, a `failure` becomes an
|
|
407
|
+
`ActionResult.failure` (`expected`) or a `ConnectorError` (`error`), and `notEmulated` fails closed
|
|
408
|
+
with a `transport_failed` `ConnectorError`. `makeEmailReplayBackend(fixtures)` replays email
|
|
409
|
+
`PortFixture`s (each fixture answers at most once; a call takes the first unused matching fixture; anything else is refused and ledgered), and the
|
|
410
|
+
fixture-driven fake in `@yolk-sdk/emulators/email` plugs in the same way (connectors never depend on
|
|
411
|
+
emulators). Neither is a production adapter. Write cases create their own `yolk-conformance`
|
|
412
|
+
draft and permanently delete it again (or restore the seeded flags), failing with
|
|
413
|
+
`EmailConformanceRestoreFailed` instead of hiding a failed restore; the three send cases are
|
|
414
|
+
`write-irreversible` and run live only when started by id. Live verification needs a host
|
|
415
|
+
`EmailClient` implementation connected to a practice mailbox; no live probe ships in this
|
|
416
|
+
repository.
|
|
417
|
+
|
|
126
418
|
## Google connector
|
|
127
419
|
|
|
128
420
|
```ts
|
|
129
421
|
import { Effect } from 'effect'
|
|
130
|
-
import {
|
|
131
|
-
makeCredentialBinding,
|
|
132
|
-
makeIntegration
|
|
133
|
-
} from '@yolk-sdk/connectors'
|
|
422
|
+
import { makeCredentialBinding, makeIntegration } from '@yolk-sdk/connectors'
|
|
134
423
|
import { GoogleConnector, GoogleOAuthCredentialSlot } from '@yolk-sdk/connectors/google'
|
|
135
424
|
|
|
136
425
|
const integration = makeIntegration({
|
|
@@ -143,28 +432,1473 @@ const integration = makeIntegration({
|
|
|
143
432
|
]
|
|
144
433
|
})
|
|
145
434
|
|
|
146
|
-
const
|
|
435
|
+
const gmailProgram = GoogleConnector.invoke({
|
|
147
436
|
integration,
|
|
148
437
|
action: 'gmail.search',
|
|
149
438
|
input: { query: 'from:alice@example.com', maxResults: 10 }
|
|
150
439
|
})
|
|
440
|
+
|
|
441
|
+
const driveProgram = GoogleConnector.invoke({
|
|
442
|
+
integration,
|
|
443
|
+
action: 'drive.list_files',
|
|
444
|
+
input: { parentId: 'folder-id', pageSize: 100 }
|
|
445
|
+
})
|
|
446
|
+
```
|
|
447
|
+
|
|
448
|
+
Provide `CredentialResolver` and `ConnectorHttpClient` layers from host code. Hosts own OAuth refresh before returning `OAuthCredential`. If using Effect HTTP, adapt `effect/http` in host code rather than importing a Yolk wrapper. Preserve connector request headers and body content type when adapting HTTP; provider connectors may rely on `content-type: application/json` for request parsing.
|
|
449
|
+
|
|
450
|
+
Gmail draft compose, update, and reply inputs accept optional `from` values for Gmail send-as aliases. Explicit `from` values are validated through `users.settings.sendAs`; reply drafts can infer a matching alias from recipient headers. Google exports action-scoped OAuth slots such as `GoogleGmailComposeOAuthCredentialSlot`, `GoogleGmailDraftReplyOAuthCredentialSlot`, `GoogleCalendarEventsOAuthCredentialSlot`, `GoogleDriveMetadataReadonlyOAuthCredentialSlot`, and `GoogleDriveFileOAuthCredentialSlot`; hosts should request the selected slot's `requiredScopes`. `GoogleOAuthCredentialSlot` keeps the generic `google.oauth` binding id for existing integrations, while `GoogleCombinedOAuthCredentialSlot` contains the existing broad-consent scope set (its `gmail.compose` grant already permits sending).
|
|
451
|
+
|
|
452
|
+
Gmail draft compose, update, and reply inputs also take an optional `contentType` (`GmailDraftContentType`: `'text' | 'html'`; `text` when omitted). A `text` body is sent as 7-bit `multipart/alternative`: a text/plain part with the body (line breaks as CRLF) and a text/html part derived from it (escaped, `<br>` per line break, runs of spaces kept, `http(s)` URLs linked to themselves, inside `<div dir="ltr">`), both quoted-printable with lines of at most 76 characters and the constant boundary `=_yolk-draft-alternative`, which quoted-printable output cannot contain. Gmail web hard-wraps a text/plain-only draft at about 70 columns when a person sends it; the HTML alternative keeps it in rich mode, so recipients see paragraphs unwrapped. On send, Gmail web still regenerates the text/plain alternative from the HTML and wraps it at about 76 columns; write each paragraph as one line. An `html` body is sent as one quoted-printable text/html part.
|
|
453
|
+
|
|
454
|
+
Gmail draft compose, update, and reply inputs also take optional `attachments` (`GmailDraftAttachments`): an array of `GmailDraftAttachment` `{ filename, mimeType, contentBase64 }`, the same `filename`/`mimeType` pair `gmail.list_attachments` reports and the standard-base64 `contentBase64` `gmail.get_attachment` returns. At most 10 attachments (`gmailDraftAttachmentsMaxItems`) of at most 25 MiB decoded in total (`gmailDraftAttachmentsMaxBytes`); `filename` is 1 to 255 characters without control characters, `/`, `\`, bidirectional controls, line separators, or lone surrogates, and not only dots; `mimeType` is an RFC 6838 `type/subtype` without parameters (`multipart/*` and `message/*` are refused); `contentBase64` is canonical padded standard base64 without line breaks (each field is also exported as its own schema: `GmailDraftAttachmentFilename`, `GmailDraftAttachmentMimeType`, `GmailDraftAttachmentBase64`). An empty array means no attachments. With attachments the draft body is 7-bit `multipart/mixed` under the constant boundary `=_yolk-draft-mixed`: the unchanged body (`multipart/alternative` or text/html) first, then one base64 part per attachment (lines of at most 76 characters; non-ASCII or long names as RFC 2047 `name` and RFC 2231 `filename*`), and the headers and reply derivation stay as without attachments. It is written with one never-retried simple multipart media upload (`POST https://gmail.googleapis.com/upload/gmail/v1/users/me/drafts?uploadType=multipart`, or `PUT .../drafts/{id}?uploadType=multipart` for an update; `multipart/related` with the JSON draft metadata `{ message: { threadId? } }` or `{ id, message: {} }`, then `message/rfc822`), so host HTTP adapters must forward that body exactly as UTF-8 and accept outgoing bodies up to about 35 MiB; header text left unencoded (such as a non-ASCII address) is uploaded as UTF-8, the same bytes `raw` would carry. A draft with attachments whose decoded MIME exceeds 35 MiB (`gmailDraftMessageMaxBytes`) fails before credentials or any request (a reply checks its body MIME before any request and the whole message after reading the original, before writing) with a `validation_failed` `ConnectorError` whose `underlying` is `{ outcome: 'rejected', retryable: false, reason: 'too_large' }`. Without attachments the drafts are written exactly as before, through the JSON endpoint. `gmail.draft_update` replaces the whole message, so attachments not sent again are removed.
|
|
455
|
+
|
|
456
|
+
`gmail.send_message` (`gmailSendMessageAction`, access `destructive`) accepts
|
|
457
|
+
`GmailSendMessageInput`: `{ raw, threadId? }`. `raw` is a complete host-generated RFC 5322 MIME
|
|
458
|
+
message encoded as canonical padded or unpadded base64url (`GmailRawMessage`); the SDK validates
|
|
459
|
+
encoding and forwards the decoded MIME unchanged, but does not parse MIME or validate recipients/send-as aliases.
|
|
460
|
+
The action always sends exactly one request, never resumable and never retried. 7-bit MIME uses
|
|
461
|
+
the simple multipart media upload
|
|
462
|
+
`POST https://gmail.googleapis.com/upload/gmail/v1/users/me/messages/send?uploadType=multipart`
|
|
463
|
+
with `Content-Type: multipart/related`: an `application/json; charset=UTF-8` metadata part (`{}`,
|
|
464
|
+
or `{ "threadId": ... }` only when provided) and a `message/rfc822` part holding the decoded MIME.
|
|
465
|
+
The boundary is chosen so it never occurs in the MIME. MIME containing any byte `>= 0x80` cannot
|
|
466
|
+
cross the string HTTP port exactly, so it keeps the JSON `{ raw, threadId? }` request to
|
|
467
|
+
`/gmail/v1/users/me/messages/send` (the previous behaviour); prefer 7-bit transfer encodings for
|
|
468
|
+
large messages. Host HTTP adapters must preserve the `multipart/related` content type and forward
|
|
469
|
+
the string body exactly (CRLF line endings, no re-encoding) and accept outgoing bodies up to about
|
|
470
|
+
35 MiB. Before resolving credentials or sending anything, decoded MIME larger than 35 MiB
|
|
471
|
+
(`gmailSendMessageMaxBytes`) fails with a `ConnectorError` `validation_failed` carrying
|
|
472
|
+
`underlying: { outcome: 'rejected', retryable: false, reason: 'too_large' }`: nothing was sent.
|
|
473
|
+
`reason: 'invalid_encoding'` is a defensive guard for undecodable base64url. The
|
|
474
|
+
`ConnectorHttpRequest` port has no timeout field; host adapters own request timeouts, and a timeout
|
|
475
|
+
after dispatch must surface as a transport failure (unknown outcome).
|
|
476
|
+
Hosts own MIME construction, header-injection protection, sender/account binding, recipient and
|
|
477
|
+
content review, size limits, and explicit sending authorization. Gmail routes to the MIME
|
|
478
|
+
To/Cc/Bcc headers, not a separate SMTP envelope: configure the encoder to retain Bcc for submission.
|
|
479
|
+
No MIME or transport library is added to the SDK. Replies need the original RFC Message-ID in `In-Reply-To`, the appropriate
|
|
480
|
+
`References` chain, and a matching Subject plus Gmail `threadId`; a Gmail resource ID is not an RFC
|
|
481
|
+
Message-ID. Changing the subject can start a new conversation. See Google's
|
|
482
|
+
[threading requirements](https://developers.google.com/workspace/gmail/api/guides/threads).
|
|
483
|
+
|
|
484
|
+
Sending selects `GoogleGmailSendOAuthCredentialSlot` with `googleGmailSendScopes` (`gmail.send`)
|
|
485
|
+
and the existing `google.oauth` binding. These are least-privilege consent hints: Google's
|
|
486
|
+
[`messages.send`](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/send)
|
|
487
|
+
also accepts `gmail.compose`, `gmail.modify`, or `https://mail.google.com/`. The action inspects the
|
|
488
|
+
resolved OAuth credential's scopes through the scope-free binding, then re-resolves through the
|
|
489
|
+
selected operation slot: send first, otherwise an existing compose/modify/full-mail grant. The host
|
|
490
|
+
still enforces that slot; inspection alone never authorizes sending. Bearer credentials or absent
|
|
491
|
+
scope metadata fall back to the send slot. No additional consent or combined-scope change is made. Success returns `GmailSendMessageOutput`
|
|
492
|
+
`{ accepted: true, id, threadId? }`, meaning provider submission, **not delivery**. Recognized HTTP rejections
|
|
493
|
+
return `gmail_send_message_rejected`; ambiguous HTTP failures return `gmail_send_message_unknown`.
|
|
494
|
+
Both omit retry hints and carry `underlying: { outcome: 'rejected' | 'unknown', retryable: false }`.
|
|
495
|
+
Transport errors or invalid success acknowledgements are typed `ConnectorError`s with the unknown
|
|
496
|
+
metadata. No automatic retry occurs. Hosts must reconcile an unconfirmed send before proposing
|
|
497
|
+
another; a deterministic Message-ID does not make sending idempotent. Keep raw sending out of
|
|
498
|
+
model tool allowlists when it is intended only for a host-owned reviewed action.
|
|
499
|
+
|
|
500
|
+
`gmail.get_thread` requires `threadId` and `format: 'full' | 'metadata' | 'minimal'`. It returns `GmailThreadOutput` with normalized messages, selected headers, decoded message text when the provider includes it (Gmail answers `body.data` transfer-decoded, so a part's `Content-Transfer-Encoding` is never applied again), and attachment metadata. Plain text is preferred over HTML; text attachments never become message bodies. Raw MIME and attachment content are omitted. Use `gmail.list_attachments` with one `messageId` for metadata-only discovery without fetching a whole thread; its `attachments` field is an Effect `Chunk`, and metadata includes inline/content-ID details when Gmail supplies them. When an attachment has `attachmentId`, fetch it with `gmail.get_attachment`; the typed output preserves Gmail's `size` and base64url `data` fields and adds standard-base64 `contentBase64` plus the input IDs. Its optional `filename` and `mimeType` inputs (the values `gmail.list_attachments` reports) are echoed unverified in the output and name the file it yields as an agent tool (`fileOutput`, ADR 0009): the tool resolves to `{ value, files }`, `value` the metadata output and `files` the attachment as a `FileRef` (or `FileUnavailable`). Gmail inline attachments may omit `attachmentId` and remain discoverable but cannot be retrieved through that action. Use `full` when decoded bodies are required.
|
|
501
|
+
|
|
502
|
+
`gmail.list_threads` (`gmailListThreadsAction`, read, `gmail.readonly` slot) sends
|
|
503
|
+
`GET /users/me/threads` with the `gmail.list` filters (`GmailListThreadsInput`: `query`, `labelId`,
|
|
504
|
+
`maxResults`, `pageToken`, `isRead`, `isFlagged`, composed into `q` exactly as for `gmail.list`) and
|
|
505
|
+
returns decoded `GmailListThreadsOutput` `{ threads?: [{ id, snippet?, historyId? }],
|
|
506
|
+
nextPageToken?, resultSizeEstimate? }`, one page per call; failures map like the other Gmail reads
|
|
507
|
+
(`gmail_list_threads_failed` otherwise). A thread listing costs 10 Gmail quota units against 5 for
|
|
508
|
+
`messages.list`, but names each conversation once.
|
|
509
|
+
|
|
510
|
+
`gmail.get_message` and `gmail.get_thread` accept optional `metadataHeaders`
|
|
511
|
+
(`GmailMetadataHeaders`: 1 to `gmailMetadataHeadersMaxItems` (50) `GmailMetadataHeaderName`
|
|
512
|
+
values, each an RFC 5322 field name of 1 to 128 printable ASCII characters without `:`), sent as
|
|
513
|
+
repeated `metadataHeaders` query parameters so Gmail answers only those headers. It is valid only
|
|
514
|
+
with `format: 'metadata'`: any other combination fails input validation before credentials or
|
|
515
|
+
HTTP, and `GmailGetMessageInput.make` / `GmailGetThreadInput.make` throw on it. With a selection,
|
|
516
|
+
`gmail.get_thread` keeps exactly the selected headers (case-insensitive) instead of its default
|
|
517
|
+
conversation headers. Omitted, requests and outputs are unchanged.
|
|
518
|
+
|
|
519
|
+
Gmail labels use `gmail.list_labels`, `gmail.create_label`, `gmail.get_label`,
|
|
520
|
+
`gmail.update_label`, `gmail.delete_label`, and `gmail.modify_labels`, plus `gmail.set_starred`
|
|
521
|
+
for starring via the `STARRED` system label. Label reads use the
|
|
522
|
+
existing `gmail.readonly` slot; label lifecycle mutations and message label changes reuse the
|
|
523
|
+
existing `gmail.modify` slot, so no broader consent is needed. Create and update accept `name`
|
|
524
|
+
plus optional `messageListVisibility` (`show` | `hide`) and `labelListVisibility` (`labelShow` |
|
|
525
|
+
`labelShowIfUnread` | `labelHide`); update renames through `PATCH` and requires at least one
|
|
526
|
+
field. Delete answers `204` with an empty body and returns a typed `{ id, deleted: true }`
|
|
527
|
+
result without JSON decoding. Label ids are encoded once and dot-only ids are rejected to avoid
|
|
528
|
+
URL normalization. Labels with `type: 'system'` (such as `INBOX`) cannot be renamed or deleted;
|
|
529
|
+
the provider rejects those mutations.
|
|
530
|
+
|
|
531
|
+
Gmail messages report `isRead` (derived as `!labelIds.includes('UNREAD')`) and `isFlagged`
|
|
532
|
+
(`labelIds.includes('STARRED')`) wherever labels are present; omitted labels assert neither, and
|
|
533
|
+
provider-supplied lookalikes are ignored. `gmail.search` and `gmail.list` accept optional
|
|
534
|
+
`isRead`/`isFlagged` booleans composed into one `q` value with the existing query grouped first.
|
|
535
|
+
`gmail.set_read` flips `UNREAD` through the `gmail.modify` slot and returns the normalized message
|
|
536
|
+
with sanitized failures.
|
|
537
|
+
|
|
538
|
+
Explicit Gmail batch actions (`gmail.batch_set_read`, `gmail.batch_set_starred`,
|
|
539
|
+
`gmail.batch_modify_labels`, `gmail.batch_trash`, `gmail.batch_untrash`, and the destructive
|
|
540
|
+
`gmail.delete_permanently`) take 1-100 unique nonempty path-safe message IDs and return shared
|
|
541
|
+
`EmailBatchOperationOutput` with complete per-ID outcomes in `messageIds` order, exact counts, and
|
|
542
|
+
sanitized codes only. Execution issues individually addressed requests sequentially and never the bulk
|
|
543
|
+
endpoints, whose empty success cannot establish per-ID outcomes. Label deltas are deduplicated with removal winning
|
|
544
|
+
and capped at 100 entries each; labels are never created. Permanent deletion issues individual
|
|
545
|
+
`DELETE` requests (only 204 confirms success; 404 is an honest rejection) through the opt-in
|
|
546
|
+
`GoogleGmailFullMailOAuthCredentialSlot` (`https://mail.google.com/`), which is never added to the
|
|
547
|
+
combined/default consent. It is immediate deletion, not trash, and claims no backup erasure.
|
|
548
|
+
|
|
549
|
+
Gmail discovery omits invalid optional attachment sizes; present sizes are nonnegative integers.
|
|
550
|
+
Best-effort malformed **optional** sizes (`-1`, `1.5`, `null`, `"12"`, missing) omit size and keep
|
|
551
|
+
siblings, including zero. Null / array-shaped / non-object parts are skipped.
|
|
552
|
+
`message/rfc822` is an attachment (no nested body recursion). Size normalization never changes
|
|
553
|
+
attachment identity or bytes; `gmail.get_attachment` returns `size` plus base64url `data`.
|
|
554
|
+
|
|
555
|
+
`gmail.get_thread` and `gmail.list_attachments` admit internal MIME `payload` as `Schema.Json` after
|
|
556
|
+
`Schema.fromJsonString(Schema.Unknown)`. `Schema.Json` requires finite numbers: raw HTTP JSON `1e999` parses to
|
|
557
|
+
`Infinity` and rejects the **whole** thread/message payload (`ConnectorError` `validation_failed`,
|
|
558
|
+
`Invalid response shape`). That is not a general collapse of malformed optional MIME fields. Do not
|
|
559
|
+
demonstrate overflow with `JSON.stringify(Infinity)` — that becomes `null` and would hit the
|
|
560
|
+
omit-size path. Provider size metadata is not a substitute for validating actual bytes. The host
|
|
561
|
+
`ConnectorHttpClient` adapter must cap streamed bytes before returning its string body. Keep
|
|
562
|
+
ordinary/error limits separate from successful attachment retrieval limits, allowing bounded base64
|
|
563
|
+
expansion and JSON overhead only for trusted attachment routes. Hosts also validate encoded length
|
|
564
|
+
and actual decoded per-file/aggregate size, and own canonical encoding checks, MIME policy, storage,
|
|
565
|
+
scanning, and extraction.
|
|
566
|
+
|
|
567
|
+
Calendar create/update boundaries use exactly one non-empty field: `{ date, timeZone? }` for an
|
|
568
|
+
all-day boundary or `{ dateTime, timeZone? }` for a date-time boundary. `start` and `end` reject
|
|
569
|
+
`null`, empty values, missing boundary fields, and objects that provide both `date` and `dateTime`.
|
|
570
|
+
`calendar.update_event` is a PATCH: omitted fields stay unchanged, but `attendees` replaces the whole
|
|
571
|
+
guest list when given.
|
|
572
|
+
|
|
573
|
+
Calendar create, update, and delete accept optional `sendUpdates` (`GoogleCalendarSendUpdates`),
|
|
574
|
+
sent as Google's `sendUpdates` query parameter: `all` notifies every guest, `externalOnly` only
|
|
575
|
+
guests who do not use Google Calendar, and `none` nobody (Google warns `none` can stop the event
|
|
576
|
+
syncing to guests' other calendars or lose it for some guests). Without it, Google's default sends no invitation, update, or
|
|
577
|
+
cancellation email (Google notes some emails might still be sent), so hosts that want guests
|
|
578
|
+
notified must pass it. `calendar.delete_event` takes `GoogleCalendarDeleteEventInput` (existing `GoogleCalendarEventIdInput` values still work).
|
|
579
|
+
|
|
580
|
+
Google Drive actions list, search, and get metadata; create folders; move items to trash; and permanently delete items. The action ids are `drive.list_files`, `drive.search_files`, `drive.get_file`, `drive.create_folder`, `drive.trash_file`, and `drive.delete_file`. Metadata reads request `drive.metadata.readonly`. Mutations request the least-privilege `drive.file` scope, which only covers files the app created or that a user explicitly opened/shared with the app. Hosts that need mutations across arbitrary existing files own broader restricted-scope consent, verification, and policy. All slots still bind through `google.oauth`.
|
|
581
|
+
|
|
582
|
+
`drive.list_files` and `drive.search_files` return `GoogleDriveListFilesOutput` with a `Chunk` of files and an opaque `nextPageToken`; pass the token back through `pageToken`. Repeated file metadata such as parents and owners also decodes to `Chunk`. Trashed items are excluded unless `includeTrashed` is true. Optional `driveId` targets one shared drive using `corpora=drive`; requests include current shared-drive support parameters. Pass a returned link-shared file `resourceKey` with get/trash/delete, or `parentResourceKey` with parent-scoped list/search/create, so the connector sends `X-Goog-Drive-Resource-Keys`; `parentResourceKey` requires `parentId`. `drive.trash_file` is reversible until Google removes the item, while `drive.delete_file` permanently deletes it without moving it to trash. Hosts should authorize both as destructive and may inspect returned `capabilities` first.
|
|
583
|
+
|
|
584
|
+
Binary Drive download/export uses the host-only helpers below; uploads remain outside this SDK surface. Hosts own file-content transfer, OAuth code exchange, refresh, storage, consent UX, Google Picker integration, and restricted-scope compliance.
|
|
585
|
+
|
|
586
|
+
## GitHub connector
|
|
587
|
+
|
|
588
|
+
`GithubConnector` works against exactly one repository taken from integration config. The model
|
|
589
|
+
never supplies `owner` or `repo`.
|
|
590
|
+
|
|
591
|
+
```ts
|
|
592
|
+
import { makeCredentialBinding, makeIntegration } from '@yolk-sdk/connectors'
|
|
593
|
+
import { GithubConnector, githubTokenSlotId } from '@yolk-sdk/connectors/github'
|
|
594
|
+
|
|
595
|
+
const integration = makeIntegration({
|
|
596
|
+
connectorId: 'github',
|
|
597
|
+
config: { owner: 'acme', repo: 'widgets' },
|
|
598
|
+
credentialBindings: [makeCredentialBinding({ slotId: githubTokenSlotId, credentialRef: 'gh' })]
|
|
599
|
+
})
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
- `github.token` (`GithubTokenSlot`) accepts `BearerTokenCredential`, `ApiKeyCredential`, or
|
|
603
|
+
`OAuthCredential` (installation token, PAT, or OAuth token) and is used by every action.
|
|
604
|
+
- Requests send `X-GitHub-Api-Version: 2026-03-10`. Outputs are normalized (never raw payloads),
|
|
605
|
+
long bodies, messages, patches, fragments, and file contents are truncated with a sibling
|
|
606
|
+
boolean flag (`bodyTruncated`, `patchTruncated`, `truncated`, …), and lists take
|
|
607
|
+
`perPage`/`page` and return `hasNextPage` from the `Link` header.
|
|
608
|
+
- Provider errors return `ActionResult.failure` with `github_unauthorized`, `github_forbidden`,
|
|
609
|
+
`github_not_found`, `github_rate_limited` (with `retryAfterMs`), `github_validation`,
|
|
610
|
+
`github_conflict`, or `github_request_failed`; `merge_pull_request` adds
|
|
611
|
+
`github_not_mergeable` and `get_file_contents` adds `github_unsupported_content`.
|
|
612
|
+
|
|
613
|
+
| Family | Actions (`github.*`) and access |
|
|
614
|
+
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
615
|
+
| Issues | read: `search_issues`, `list_issues`, `get_issue`, `list_assignees`, `list_issue_timeline`; write: `create_issue`, `update_issue`, `lock_issue`, `unlock_issue`, `add_assignees`, `remove_assignees` |
|
|
616
|
+
| Comments/labels | read: `list_issue_comments`, `list_labels`, `list_milestones`; write: `create_issue_comment`, `update_issue_comment`, `add_labels`, `remove_label`, `create_reaction`; destructive: `delete_issue_comment` |
|
|
617
|
+
| Structure | read: `list_sub_issues`, `list_issue_dependencies`, `list_issue_types`, `list_issue_fields`; write: `add_sub_issue`, `remove_sub_issue`, `add_blocked_by`, `remove_blocked_by`, `set_issue_field_values` |
|
|
618
|
+
| Pull requests | read: `list_pull_requests`, `get_pull_request`, `list_pull_request_files`, `list_pull_request_commits`, `get_pull_request_checks`, `list_pull_request_reviews`, `list_pull_request_review_comments`; write: `create_pull_request`, `update_pull_request`, `request_reviewers`, `create_pull_request_review`, `create_pull_request_review_comment`; destructive: `merge_pull_request` |
|
|
619
|
+
| Repository | read: `compare_commits`, `list_releases`, `get_file_contents`, `search_code` |
|
|
620
|
+
|
|
621
|
+
Issue and code search always add `repo:{owner}/{repo}` and reject queries with their own
|
|
622
|
+
`repo:`, `org:`, `user:`, or `owner:` qualifiers. Issue types and issue fields are org-level
|
|
623
|
+
and only work when `owner` is an organization. Sub-issue and dependency actions take issue
|
|
624
|
+
numbers and resolve GitHub's internal issue ids. `set_issue_field_values` adds or updates the
|
|
625
|
+
listed fields only. `merge_pull_request` requires `expectedHeadSha`, so a head that moved
|
|
626
|
+
after review fails with `github_conflict` instead of merging unreviewed commits.
|
|
627
|
+
|
|
628
|
+
### Host-only GitHub helpers
|
|
629
|
+
|
|
630
|
+
These are not actions and never appear in `GithubConnector.actions`:
|
|
631
|
+
|
|
632
|
+
- `createGithubAppInstallationToken({ appId, installationId, privateKeyPem, repositories?, repositoryIds?, permissions? })`
|
|
633
|
+
signs an RS256 App JWT with WebCrypto (PKCS#8 or GitHub's PKCS#1 download format; literal
|
|
634
|
+
`\n` escapes are normalized) and exchanges it for an installation token, optionally
|
|
635
|
+
down-scoped. Returns `{ token, expiresAt }` (epoch ms). It needs `ConnectorHttpClient`, does
|
|
636
|
+
no caching, and fails with a code-only `GithubAppTokenError`.
|
|
637
|
+
- `uploadGithubAttachment(integration, { name, contentType, bytes, repositoryId?, alt? }, budget, options?)`
|
|
638
|
+
uploads a PNG, JPEG, GIF, WebP, SVG, MP4, MOV, or WebM file (10 MB images, 100 MB videos;
|
|
639
|
+
`options` may only lower these) and returns `{ url, markdown }`. It uses GitHub's
|
|
640
|
+
**undocumented, unstable** `uploads.github.com/user-attachments/assets` endpoint through
|
|
641
|
+
`ConnectorBinaryWriteHttpClient`, and requires the optional `github.upload_token` slot to hold a
|
|
642
|
+
user token (OAuth or PAT). GitHub refuses installation tokens there (they surface as `not_found`,
|
|
643
|
+
so the helper rejects `ghs_` tokens up front). A 404 otherwise means no push access. Without
|
|
644
|
+
`repositoryId`, the helper looks it up via `GET /repos/{owner}/{repo}`.
|
|
645
|
+
|
|
646
|
+
## Kie connector
|
|
647
|
+
|
|
648
|
+
`KieConnector` submits Kie Market generation tasks and reads their status (actions: `kieActions`;
|
|
649
|
+
details in the [connector docs](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/integrations/connectors.mdx#kie)).
|
|
650
|
+
|
|
651
|
+
```ts
|
|
652
|
+
import { makeCredentialBinding, makeIntegration } from '@yolk-sdk/connectors'
|
|
653
|
+
import { kieApiKeySlotId } from '@yolk-sdk/connectors/kie'
|
|
654
|
+
|
|
655
|
+
const integration = makeIntegration({
|
|
656
|
+
connectorId: 'kie',
|
|
657
|
+
credentialBindings: [makeCredentialBinding({ slotId: kieApiKeySlotId, credentialRef: 'kie' })]
|
|
658
|
+
})
|
|
659
|
+
```
|
|
660
|
+
|
|
661
|
+
- `kie.api_key` (`KieApiKeySlot`) accepts `ApiKeyCredential`, `BearerTokenCredential`, or
|
|
662
|
+
`OAuthCredential`; its value is sent as `Authorization: Bearer <key>`. Username/password
|
|
663
|
+
credentials fail with `credential_invalid`.
|
|
664
|
+
|
|
665
|
+
Kie generation is asynchronous: `kie.create_image_task` (GPT Image 2; image-to-image when
|
|
666
|
+
`inputUrls` are given) and `kie.create_video_task` (Wan 2.7 image-to-video) return a `taskId`, and
|
|
667
|
+
`kie.get_task` returns its `state`, the raw `resultJson`, and the result URLs it carries. Both
|
|
668
|
+
create actions are `write` (each task spends Kie credits). Input URLs are fetched by Kie, not the
|
|
669
|
+
host; the connector checks only that they are absolute http(s) URLs without credentials. Kie
|
|
670
|
+
answers most failures with HTTP 200 and a non-200 envelope `code`; both that and a non-2xx status
|
|
671
|
+
become a `ProviderFailure` (`kie_unauthorized`, `kie_insufficient_credits`, `kie_validation`,
|
|
672
|
+
`kie_rate_limited`, `kie_generation_failed`, ...) whose `underlying` is `{ kieCode, msg }` (the Kie
|
|
673
|
+
envelope `code`, or the HTTP status when a non-2xx answer has no envelope, and its message when
|
|
674
|
+
present). A task that ends in `fail` is a successful `kie.get_task` read with
|
|
675
|
+
`failCode`/`failMsg`. Result URLs expire (Kie keeps generated files for 14 days); hosts copy final
|
|
676
|
+
assets to their own storage. `callBackUrl` is an action input (model-supplied when the action is a
|
|
677
|
+
tool); hosts that allow it own the webhook and its verification, and hosts that must pin it strip
|
|
678
|
+
or override it. Code-mode scripts have no timers: expose `kie.get_task` with
|
|
679
|
+
`callableBy: 'model'` (ADR 0002, "Known gap: polling").
|
|
680
|
+
|
|
681
|
+
## Fortnox connector
|
|
682
|
+
|
|
683
|
+
Wiring fragment (host layers and Effect execution omitted):
|
|
684
|
+
|
|
685
|
+
```ts
|
|
686
|
+
import { makeCredentialBinding, makeIntegration } from '@yolk-sdk/connectors'
|
|
687
|
+
import { FortnoxConnector, FortnoxOAuthCredentialSlot } from '@yolk-sdk/connectors/fortnox'
|
|
688
|
+
|
|
689
|
+
const integration = makeIntegration({
|
|
690
|
+
connectorId: 'fortnox',
|
|
691
|
+
credentialBindings: [
|
|
692
|
+
makeCredentialBinding({
|
|
693
|
+
slotId: FortnoxOAuthCredentialSlot.id,
|
|
694
|
+
credentialRef: 'host-fortnox-credential'
|
|
695
|
+
})
|
|
696
|
+
]
|
|
697
|
+
})
|
|
698
|
+
|
|
699
|
+
const program = FortnoxConnector.invoke({
|
|
700
|
+
integration,
|
|
701
|
+
action: 'fortnox.list_invoices',
|
|
702
|
+
input: { filter: 'unpaid', limit: 25 }
|
|
703
|
+
})
|
|
704
|
+
```
|
|
705
|
+
|
|
706
|
+
Provide `CredentialResolver` and `ConnectorHttpClient`. The resolver returns a current
|
|
707
|
+
`OAuthCredential` with `provider: 'fortnox'`. No config keys are required. Hosts own OAuth code
|
|
708
|
+
exchange, state validation, serialized refresh-token rotation/persistence, revocation, consent,
|
|
709
|
+
license checks, throttling, and authorization. Exported `fortnoxOAuthAuthorizeUrl` and
|
|
710
|
+
`fortnoxOAuthTokenUrl` point to Fortnox's `apps.fortnox.se/oauth-v1/auth` and `/token` endpoints.
|
|
711
|
+
Use `access_type=offline` for refresh; token exchange uses HTTP Basic client authentication and a
|
|
712
|
+
form-urlencoded body. The connector never stores or refreshes tokens.
|
|
713
|
+
|
|
714
|
+
**Fortnox has no read-only OAuth scopes.** Action-scoped `FortnoxCompanyInformationOAuthCredentialSlot`,
|
|
715
|
+
`FortnoxCustomerOAuthCredentialSlot`, `FortnoxInvoiceOAuthCredentialSlot`,
|
|
716
|
+
`FortnoxSupplierOAuthCredentialSlot`, and `FortnoxSupplierInvoiceOAuthCredentialSlot` request
|
|
717
|
+
`companyinformation`, `customer`, `invoice`, `supplier`, and `supplierinvoice`, respectively.
|
|
718
|
+
All share `fortnox.oauth`; `FortnoxCombinedOAuthCredentialSlot` requests all five. Opt-in
|
|
719
|
+
`FortnoxArticleOAuthCredentialSlot` (`article`), `FortnoxPriceOAuthCredentialSlot` (`price`),
|
|
720
|
+
`FortnoxCostCenterOAuthCredentialSlot` (`costcenter`), `FortnoxPaymentOAuthCredentialSlot`
|
|
721
|
+
(`payment`), `FortnoxOfferOAuthCredentialSlot` (`offer`), `FortnoxPrintOAuthCredentialSlot`
|
|
722
|
+
(`print`), `FortnoxInboxOAuthCredentialSlot` (`inbox`), `FortnoxSettingsOAuthCredentialSlot`
|
|
723
|
+
(`settings`), and `FortnoxProfileOAuthCredentialSlot` (`profile`) are not on the combined slot. These consent hints
|
|
724
|
+
do not restrict the underlying token to reads. Read actions use `read` metadata; customer and invoice
|
|
725
|
+
create/update actions use `write` metadata: `fortnox.create_customer`, `fortnox.update_customer`,
|
|
726
|
+
`fortnox.create_invoice`, and `fortnox.update_invoice`. Customer invoices have no send or book
|
|
727
|
+
action. The original read actions are
|
|
728
|
+
`fortnox.get_company_information`, `fortnox.list_customers`, `fortnox.get_customer`,
|
|
729
|
+
`fortnox.list_invoices`, `fortnox.get_invoice`, `fortnox.list_suppliers`, `fortnox.get_supplier`,
|
|
730
|
+
`fortnox.list_supplier_invoices`, `fortnox.get_supplier_invoice`, and `fortnox.list_supplier_invoice_files` (described below).
|
|
731
|
+
|
|
732
|
+
Resource modules add list/get/create/update/delete actions for articles, price lists and prices,
|
|
733
|
+
cost centers, invoice and supplier-invoice payments, offers, inbox folders, labels, predefined
|
|
734
|
+
accounts, modes of payment, terms of payment and delivery, ways of delivery, and units, plus
|
|
735
|
+
`fortnox.list_print_templates`, `fortnox.get_company_settings`, `fortnox.get_locked_period`, and
|
|
736
|
+
`fortnox.get_profile` (91 actions: 42 `read`, 31 `write`, 18 `destructive`). Deletes, payment
|
|
737
|
+
bookkeeping (`fortnox.bookkeep_*`), and offer lifecycle actions (`fortnox.create_order_from_offer`,
|
|
738
|
+
`fortnox.create_invoice_from_offer`, `fortnox.cancel_offer`, `fortnox.email_offer`,
|
|
739
|
+
`fortnox.mark_offer_sent`) are `destructive`: the Fortnox API cannot undo them, so hosts must gate
|
|
740
|
+
them with approval. New write inputs reject unknown keys. See the Fortnox guide for the full table.
|
|
741
|
+
|
|
742
|
+
Write inputs preserve Fortnox's PascalCase wire names. Creating a customer requires `Name` and lets
|
|
743
|
+
Fortnox assign `CustomerNumber`; updating a customer includes `CustomerNumber` for the URL but omits
|
|
744
|
+
it from the JSON body. Creating an invoice requires `CustomerNumber` and lets Fortnox assign
|
|
745
|
+
`DocumentNumber`; updating one includes `DocumentNumber` for the URL. Invoice `InvoiceRows` inputs
|
|
746
|
+
are JSON arrays of `FortnoxInvoiceRowInput` (a closed schema of the writable row fields: unknown
|
|
747
|
+
row keys fail `execute`, agent tool calls, and the invoice input classes' `make`), while returned row collections are Effect `Chunk` values of `FortnoxInvoiceRow`.
|
|
748
|
+
Invoice `Remarks` is the invoice text printed on the invoice; `Comments` is an internal note. Customer write inputs
|
|
749
|
+
omit Fortnox's read-only `Country` (set `CountryCode`) and list-only `Phone` (use `Phone1`/`Phone2`),
|
|
750
|
+
and the customer create/update actions reject unknown keys instead of stripping them; customer and
|
|
751
|
+
supplier responses keep both fields. Those actions' `inputSchema` is a closed wrapper, not the
|
|
752
|
+
class: build typed inputs with `FortnoxCreateCustomerInput.make` /
|
|
753
|
+
`FortnoxUpdateCustomerInput.make`; decoding those classes directly strips unknown keys. Action
|
|
754
|
+
descriptions document Fortnox update semantics (partial customer updates, invoice row replacement,
|
|
755
|
+
pre-existing referenced records). See the
|
|
756
|
+
[Fortnox guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/connectors/fortnox.mdx) for the action table and schema
|
|
757
|
+
conventions.
|
|
758
|
+
|
|
759
|
+
List inputs support `page` (at least 1), `limit` (1–500; provider default 100), `lastModified`, and
|
|
760
|
+
one `search: { field, value }` pair with resource-specific fields. Customers accept active/inactive
|
|
761
|
+
`filter`; invoice lists accept status `filter` and `fromDate`/`toDate`. Each list returns one page:
|
|
762
|
+
`{ customers | invoices | suppliers | supplierInvoices, pagination }`. Collections are runtime
|
|
763
|
+
Effect Chunks. `pagination` contains `currentPage`, `totalPages`, `totalResources`, and optional
|
|
764
|
+
`nextPage`; repeat the same selection and limit with `page: nextPage` until it is absent.
|
|
765
|
+
|
|
766
|
+
Get inputs use branded `customerNumber` (`FortnoxCustomerNumber`), `documentNumber`
|
|
767
|
+
(`FortnoxDocumentNumber`), `supplierNumber` (`FortnoxSupplierNumber`), or numeric-string
|
|
768
|
+
`givenNumber` (`FortnoxGivenNumber`). The latter is Fortnox's **GivenNumber**, not the supplier's
|
|
769
|
+
plain-string InvoiceNumber; the brands are nominally incompatible and keep their string wire
|
|
770
|
+
representation. File discovery (`fortnox.list_supplier_invoice_files`) filters by GivenNumber and
|
|
771
|
+
returns it on each file entry. Preview downloads take the canonical `FortnoxDocumentNumber` (URL
|
|
772
|
+
encoded, without archive-ID restrictions); archive downloads take the opaque discovery file ID.
|
|
773
|
+
Get outputs
|
|
774
|
+
unwrap the resource. Resource fields retain Fortnox spelling and selected contact, status, reference,
|
|
775
|
+
amount, and row data; they are bounded read models, not lossless accounting exports. Unknown fields
|
|
776
|
+
and supplier bank details are omitted. Optional fields can be absent from list responses; use get
|
|
777
|
+
for available `InvoiceRows` / `SupplierInvoiceRows` Chunks. Customer-invoice `Total` / `Balance` remain
|
|
778
|
+
numbers, supplier-invoice equivalents remain strings. No monetary arithmetic or rounding occurs.
|
|
779
|
+
|
|
780
|
+
Non-2xx responses are value-level provider failures, with status-specific unauthorized, forbidden,
|
|
781
|
+
not-found, and rate-limit codes. Provider error messages and codes are retained without raw error
|
|
782
|
+
bodies. Valid delta-seconds `Retry-After` becomes `retryAfterMs`; there are no automatic retries.
|
|
783
|
+
Validation, credential, malformed success, and transport failures remain typed Effect errors.
|
|
784
|
+
The HTTP adapter must preserve Bearer authorization, JSON accept headers, and JSON content-type on
|
|
785
|
+
writes; hosts own redirect safety, response-size limits, and sensitive-data handling. Customer and
|
|
786
|
+
invoice create/update never send or book invoices; payment bookkeeping and offer emailing are
|
|
787
|
+
separate `destructive` actions. Host-only preview/archive/inbox transfers are described below.
|
|
788
|
+
|
|
789
|
+
See the [official API reference](https://apps.fortnox.se/apidocs),
|
|
790
|
+
[scopes](https://www.fortnox.se/developer/guides-and-good-to-know/scopes),
|
|
791
|
+
[OAuth lifecycle](https://www.fortnox.se/developer/authorization/), and
|
|
792
|
+
[pagination/search](https://www.fortnox.se/developer/guides-and-good-to-know/parameters/).
|
|
793
|
+
|
|
794
|
+
### Fortnox conformance cases (experimental)
|
|
795
|
+
|
|
796
|
+
`@yolk-sdk/connectors/fortnox/conformance` exports conformance cases for
|
|
797
|
+
`@yolk-sdk/conformance/runner`, each checking one claim about how the real Fortnox API behaves where
|
|
798
|
+
it differs from, or goes beyond, its docs. Each case runs the real connector actions and helpers over
|
|
799
|
+
`ConnectorHttpClient`, `ConnectorBinaryHttpClient`, and `CredentialResolver`, plus the
|
|
800
|
+
`FortnoxConformanceConfig` service, which holds host-supplied seed identities in a Fortnox developer
|
|
801
|
+
test company (practice account). Cases never hard-code account data; a missing seed fails the case
|
|
802
|
+
with a `precondition:` mismatch before any request. Credentials bind through
|
|
803
|
+
`fortnoxConformanceIntegration` (`fortnox.oauth`, credential ref `fortnox.conformance`). The case
|
|
804
|
+
table, seeds, and claims live in the
|
|
805
|
+
[Fortnox guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/connectors/fortnox.mdx#conformance-cases).
|
|
806
|
+
|
|
807
|
+
The row and customer mutation cases read the original state first, always restore it afterwards
|
|
808
|
+
(also after a failed assertion or interruption), verify the restore by reading back, and fail with
|
|
809
|
+
`FortnoxConformanceRestoreFailed` when the restore fails (check the account and restore it by hand
|
|
810
|
+
if it still differs). A failed restore raised while the case is being interrupted is also handed,
|
|
811
|
+
with its full message, to `ConformanceCleanupReporter` from `@yolk-sdk/connectors/conformance`
|
|
812
|
+
(default: `Effect.logWarning`), since the interruption may replace it. The repository runner
|
|
813
|
+
(`pnpm conformance:fortnox`) turns a first Ctrl-C into an interruption and prints these reports on
|
|
814
|
+
stderr as `WARN` lines; like the shared runners, it prints every live-run line with the live access
|
|
815
|
+
token redacted. The rejection case restores nothing: it only confirms the customer is absent
|
|
816
|
+
before its write and names any invoice Fortnox unexpectedly creates for manual cancellation. The
|
|
817
|
+
email case aborts unless the invoice's `EmailInformation.EmailAddressTo` equals the `emailRecipient`
|
|
818
|
+
seed exactly; the runner never runs it live unless its exact id is allowed. Neither the rejection
|
|
819
|
+
case nor the email send reports through `ConformanceCleanupReporter`.
|
|
820
|
+
|
|
821
|
+
`fortnoxConformanceFixtures` are synthetic placeholders (`evidence: 'unverified'`) that replay with
|
|
822
|
+
`fortnoxConformanceFixtureSeeds`. `pnpm conformance:fortnox` in this repository dry-runs by default;
|
|
823
|
+
its `--live --owner-approved --account <label>` mode (refused whenever `CI` is non-empty) is for
|
|
824
|
+
owners running a practice account by hand, and a first Ctrl-C interrupts the run so a running write
|
|
825
|
+
case still restores. `--record` stages verified recordings all or nothing in a new gitignored run
|
|
826
|
+
directory, `.conformance-recordings/fortnox/<YYYY-MM-DD>T<HHMMSS>Z-<random>/`, and never writes
|
|
827
|
+
committed sources. Promotion is manual: scrub, copy into `src/fortnox/conformance/`, and update the
|
|
828
|
+
tests in the same change, because promoted fixtures change fixture ids, `evidence`, and `account`. A
|
|
829
|
+
promoted payment-filter recording also needs the tests' fixed clock (`atTestNow`) moved past the
|
|
830
|
+
recorded `DueDate`.
|
|
831
|
+
|
|
832
|
+
`@yolk-sdk/connectors/conformance` supplies the ports for such runs:
|
|
833
|
+
`connectorHttpClientFromEffectHttpClientLayer`, `connectorBinaryHttpClientFromEffectHttpClientLayer`,
|
|
834
|
+
`connectorBinaryWriteHttpClientFromEffectHttpClientLayer` (POST/PUT bytes plus `uploadSession`
|
|
835
|
+
ranges and cancellation to pre-authenticated session URLs, refusing credential headers there), or
|
|
836
|
+
all three via `connectorHttpClientsFromEffectHttpClientLayer`, over any Effect `HttpClient` (for
|
|
837
|
+
example `ReplayHttpClient.layer` or `FetchHttpClient.layer`), and `staticCredentialResolverLayer`.
|
|
838
|
+
**These are for conformance and tests only, not production adapters:** they enforce no streamed
|
|
839
|
+
byte limits, redirect, DNS/IP, timeout, or TLS policy (binary `maxBytes`/`maxErrorBodyBytes` are
|
|
840
|
+
checked only after buffering), forward `redirect: 'manual'`/`credentials: 'omit'` as
|
|
841
|
+
`FetchHttpClient.RequestInit` options, and map transport failures to code-only errors without URLs,
|
|
842
|
+
headers, or bodies. The static resolver ignores scopes and never refreshes; hosts own real
|
|
843
|
+
credential storage.
|
|
844
|
+
|
|
845
|
+
```ts
|
|
846
|
+
import { Layer } from 'effect'
|
|
847
|
+
import { OAuthCredential } from '@yolk-sdk/connectors'
|
|
848
|
+
import {
|
|
849
|
+
connectorHttpClientsFromEffectHttpClientLayer,
|
|
850
|
+
staticCredentialResolverLayer
|
|
851
|
+
} from '@yolk-sdk/connectors/conformance'
|
|
852
|
+
import {
|
|
853
|
+
FortnoxConformanceConfig,
|
|
854
|
+
fortnoxConformanceCases,
|
|
855
|
+
fortnoxConformanceFixtureSeeds,
|
|
856
|
+
fortnoxConformanceFixtures
|
|
857
|
+
} from '@yolk-sdk/connectors/fortnox/conformance'
|
|
858
|
+
import { ReplayHttpClient } from '@yolk-sdk/conformance/replay'
|
|
859
|
+
import { runConformance } from '@yolk-sdk/conformance/runner'
|
|
860
|
+
|
|
861
|
+
const report = runConformance(fortnoxConformanceCases, {
|
|
862
|
+
target: { kind: 'replay' },
|
|
863
|
+
fixtures: fortnoxConformanceFixtures,
|
|
864
|
+
layer: testCase =>
|
|
865
|
+
Layer.mergeAll(
|
|
866
|
+
connectorHttpClientsFromEffectHttpClientLayer.pipe(
|
|
867
|
+
Layer.provide(
|
|
868
|
+
ReplayHttpClient.layer(
|
|
869
|
+
fortnoxConformanceFixtures.filter(fixture => testCase.fixtures.includes(fixture.id))
|
|
870
|
+
)
|
|
871
|
+
)
|
|
872
|
+
),
|
|
873
|
+
staticCredentialResolverLayer(
|
|
874
|
+
OAuthCredential.make({ provider: 'fortnox', accessToken: 'replay', expiresAt: 0 })
|
|
875
|
+
),
|
|
876
|
+
Layer.succeed(FortnoxConformanceConfig, fortnoxConformanceFixtureSeeds)
|
|
877
|
+
)
|
|
878
|
+
})
|
|
879
|
+
```
|
|
880
|
+
|
|
881
|
+
## Dropbox connector
|
|
882
|
+
|
|
883
|
+
Minimal wiring fragment (host layer and Effect execution omitted):
|
|
884
|
+
|
|
885
|
+
```ts
|
|
886
|
+
import { makeCredentialBinding, makeIntegration } from '@yolk-sdk/connectors'
|
|
887
|
+
import { DropboxConnector, DropboxCombinedOAuthCredentialSlot } from '@yolk-sdk/connectors/dropbox'
|
|
888
|
+
|
|
889
|
+
const integration = makeIntegration({
|
|
890
|
+
connectorId: 'dropbox',
|
|
891
|
+
credentialBindings: [
|
|
892
|
+
makeCredentialBinding({
|
|
893
|
+
slotId: DropboxCombinedOAuthCredentialSlot.id,
|
|
894
|
+
credentialRef: 'dropbox-oauth-credential'
|
|
895
|
+
})
|
|
896
|
+
]
|
|
897
|
+
})
|
|
898
|
+
|
|
899
|
+
const program = DropboxConnector.invoke({
|
|
900
|
+
integration,
|
|
901
|
+
action: 'dropbox.list_folder',
|
|
902
|
+
input: { path: '', limit: 100 }
|
|
903
|
+
})
|
|
904
|
+
```
|
|
905
|
+
|
|
906
|
+
Provide host-owned `CredentialResolver` and `ConnectorHttpClient` layers. Dropbox action-scoped slots share the `dropbox.oauth` binding id: metadata reads request `files.metadata.read`, create/move/copy/delete actions request `files.content.write`, and the host-only download helper below requests `files.content.read` through `DropboxContentReadOAuthCredentialSlot`. `DropboxCombinedOAuthCredentialSlot` now hints all three. The host owns OAuth code exchange, refresh, storage, consent, and App Folder versus Full Dropbox configuration.
|
|
907
|
+
|
|
908
|
+
Use `path: ''` or omit `path` to list the Dropbox API root. Continue folder listings with `dropbox.list_folder_continue` while `hasMore` is true, and continue searches with `dropbox.search_continue`. Outputs normalize Dropbox `.tag` metadata into `type: 'file' | 'folder' | 'deleted'` and camelCase fields.
|
|
909
|
+
|
|
910
|
+
Upload and download **actions** are intentionally not included: Dropbox content routes are binary, while the portable connector HTTP port carries string bodies. Original-byte download and create/update are available only through separate host helpers below.
|
|
911
|
+
|
|
912
|
+
### Host integration: download Dropbox file bytes
|
|
913
|
+
|
|
914
|
+
`downloadDropboxFile` from `@yolk-sdk/connectors/dropbox` downloads **bytes only**, mirroring
|
|
915
|
+
`downloadOneDriveItem`. It is not a connector action and is never automatically serialized by
|
|
916
|
+
`makeConnectorToolModule`. A host must supply an **app-owned materialization/read tool** to
|
|
917
|
+
store/scan/extract the bytes and expose bounded, provenance-bearing reader output. A skill can help
|
|
918
|
+
select paths or IDs; it cannot itself download or read a file. Search highlights and
|
|
919
|
+
`get_metadata` output are not file contents.
|
|
920
|
+
|
|
921
|
+
```ts
|
|
922
|
+
import { downloadDropboxFile } from '@yolk-sdk/connectors/dropbox'
|
|
923
|
+
|
|
924
|
+
// Host code: provide existing CredentialResolver and a compliant ConnectorBinaryHttpClient layer.
|
|
925
|
+
// The path comes from discovery. This example assumes host-owned integration and selectedFile values.
|
|
926
|
+
const download = downloadDropboxFile(
|
|
927
|
+
integration,
|
|
928
|
+
{ path: selectedFile.id },
|
|
929
|
+
{ maxBytes: 20 * 1024 * 1024, maxErrorBodyBytes: 16 * 1024 }
|
|
930
|
+
)
|
|
151
931
|
```
|
|
152
932
|
|
|
153
|
-
|
|
933
|
+
The third argument is trusted **host configuration**, separate from tool parameters. Both
|
|
934
|
+
nonnegative safe-integer budgets are required; `maxBytes: 0` permits valid empty files. The helper
|
|
935
|
+
needs the root `ConnectorBinaryHttpClient` port plus `CredentialResolver`; the existing
|
|
936
|
+
`ConnectorHttpClient` and default `DropboxConnector` dependencies are unchanged. File bytes are an
|
|
937
|
+
untouched `Uint8Array`, not text or base64 model content.
|
|
938
|
+
|
|
939
|
+
`path` accepts one Dropbox `/path`, bare `id:` file identifier, folder-ID-relative path
|
|
940
|
+
(`id:folder-id/child.txt`), `rev:` revision, or `ns:` namespace path; share links, unrooted
|
|
941
|
+
relative paths, blank values, and control characters are rejected before any
|
|
942
|
+
credential or network use. The value is sent as ASCII-escaped `Dropbox-API-Arg` JSON, so non-ASCII
|
|
943
|
+
names are preserved exactly. No `Dropbox-API-Path-Root` or `Dropbox-API-Select-User` header is sent.
|
|
944
|
+
|
|
945
|
+
The helper issues a single `GET` to `content.dropboxapi.com/2/files/download`. Dropbox serves
|
|
946
|
+
bytes directly; every 3xx fails with `unexpected_redirect` and is never followed. Metadata comes
|
|
947
|
+
from the `Dropbox-API-Result` header of that same response, so it describes the served revision,
|
|
948
|
+
but the helper does not verify `contentHash`. Exactly one result header is required; bare `id:`
|
|
949
|
+
and `rev:` requests must match the returned identity. Folder-ID-relative paths return the child's
|
|
950
|
+
own ID, not the folder address. Body length must equal metadata `size`; Paper
|
|
951
|
+
and other non-downloadable entries fail with `not_downloadable` (use Dropbox export flows instead).
|
|
952
|
+
|
|
953
|
+
Errors expose only the typed `DropboxDownloadError.code`: `invalid_input`, `credential_failed`,
|
|
954
|
+
`transport_failed`, `network_policy_rejected`, `response_too_large`, `unauthorized`, `forbidden`,
|
|
955
|
+
`not_found`, `rate_limited`, `upstream_failed`, `invalid_metadata`, `not_a_file`,
|
|
956
|
+
`not_downloadable`, `unexpected_redirect`, and `partial_content`. Dropbox 409 bodies are parsed
|
|
957
|
+
only to classify `error_summary`; bodies, URLs, headers, and wrapped causes are discarded.
|
|
958
|
+
|
|
959
|
+
The host adapter contract is identical to the Microsoft helper's (see below): no automatic
|
|
960
|
+
redirects, cookies, or ambient auth; connection-time public DNS/IP policy; TLS; timeouts and
|
|
961
|
+
cancellation; and actual streamed byte limits with `response_too_large` on overflow and
|
|
962
|
+
`bodyComplete: false` only for bounded non-200 bodies. Offline fake-port tests cover protocol flow,
|
|
963
|
+
byte identity, bounds, status handling, and redaction, not socket enforcement.
|
|
964
|
+
|
|
965
|
+
### Dropbox conformance cases (experimental)
|
|
966
|
+
|
|
967
|
+
`@yolk-sdk/connectors/dropbox/conformance` exports eight conformance cases for
|
|
968
|
+
`@yolk-sdk/conformance/runner` (`dropboxConformanceCases`), synthetic replay fixtures
|
|
969
|
+
(`dropboxConformanceFixtures`, `evidence: 'unverified'`), and the seeds they replay with
|
|
970
|
+
(`dropboxConformanceFixtureSeeds`). Every case runs the real connector actions, or the host-only
|
|
971
|
+
`createDropboxFile` / `updateDropboxFile` helpers, over `ConnectorHttpClient`,
|
|
972
|
+
`ConnectorBinaryWriteHttpClient`, and `CredentialResolver` plus `DropboxConformanceConfig`, which
|
|
973
|
+
holds host-supplied seed paths in a practice Dropbox account. They cover list and search cursor
|
|
974
|
+
paging, case-insensitive path lookups, the HTTP 409 error envelope, folder conflicts, delete then
|
|
975
|
+
not-found, single-item copy/move metadata, and the upload rev precondition. Credentials bind through
|
|
976
|
+
`dropboxConformanceIntegration` (`dropbox.oauth`, credential ref `dropbox.conformance`). The case
|
|
977
|
+
table, seeds, and claims live in the
|
|
978
|
+
[Dropbox conformance guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/connectors/dropbox.mdx#conformance-cases).
|
|
979
|
+
The Dropbox emulator (`@yolk-sdk/emulators/dropbox`) passes every case offline.
|
|
980
|
+
|
|
981
|
+
Every write case works only inside its own `yolk-conformance-<runId>-<case>` folder under the
|
|
982
|
+
`workFolderPath` seed. The `runId` seed makes that namespace unique per invocation (the fixtures
|
|
983
|
+
replay with `run-synthetic`; the live runner generates a fresh random id every time), so concurrent
|
|
984
|
+
runs are supported only through distinct run ids. A case proves its folder path absent before
|
|
985
|
+
writing, and registers the created entry together with the create (uninterruptibly). A definitive
|
|
986
|
+
create rejection (HTTP 4xx other than 408, such as `path/conflict`) deletes nothing. An ambiguous create (a
|
|
987
|
+
transport or decoding failure, no status, HTTP 408, or HTTP 5xx) gets one best-effort delete of the owned path
|
|
988
|
+
but always fails with `DropboxConformanceActionFailed` (`createOutcome: 'unknown'`) naming the
|
|
989
|
+
exact path to check by hand; so do the conflict case's duplicate creates, after the known original
|
|
990
|
+
is cleaned up. Every later write inside the case folder is masked too, so no aborted request lands
|
|
991
|
+
after the cleanup. After a successful create, the cleanup deletes the entry by id (a not-found answer
|
|
992
|
+
proves it gone; any other failure falls back to the owned path), also after a failed assertion or a
|
|
993
|
+
fiber interruption, then checks that `get_metadata` answers not-found; a failed cleanup fails with
|
|
994
|
+
`DropboxConformanceRestoreFailed` naming the path, and a create answering a path outside the case
|
|
995
|
+
folder is never deleted (`DropboxConformanceCleanupRefused`). Neither the runner nor the bridges set
|
|
996
|
+
a request timeout, so a hanging request delays an interruption. The live runner turns the first
|
|
997
|
+
SIGINT/SIGTERM into a fiber interruption, so the cleanup is attempted (not confirmed) and no
|
|
998
|
+
further case starts: a cleanup problem raised meanwhile prints as a WARN line through
|
|
999
|
+
`ConformanceCleanupReporter`, and the run still ends interrupt-only (exit 130, then the read-only
|
|
1000
|
+
leftover lookup runs again). Duplicate signals within a second (one Ctrl-C
|
|
1001
|
+
reaches every process of the foreground group) are ignored; a later signal or a kill skips the
|
|
1002
|
+
cleanup. Run live runs as `pnpm conformance:dropbox` or with `tsx` directly: `pnpm exec tsx`
|
|
1003
|
+
returns to the prompt at once on Ctrl-C (observed), so later lines print after the prompt, `$?` is
|
|
1004
|
+
pnpm's own code, and the runner must be stopped with `kill -TERM <pid>` (printed by the first-signal
|
|
1005
|
+
message). Before any write case, the runner warns read-only about `yolk-conformance-run-*` folders
|
|
1006
|
+
earlier runs left under `workFolderPath` (`findDropboxConformanceLeftovers`; bounded to 50 listing
|
|
1007
|
+
pages; every valid `runId` starts with `run-`, and a missing work folder holds none); it never
|
|
1008
|
+
deletes them. `pnpm conformance:dropbox` in this repository dry-runs by default;
|
|
1009
|
+
`--live --owner-approved --account <label>` (refused whenever `CI` is non-empty; needs
|
|
1010
|
+
`DROPBOX_ACCESS_TOKEN` and the seeds) is for owners running a practice account by hand,
|
|
1011
|
+
`--allow-writes reversible` adds the write cases, and `--record` stages verified recordings all or
|
|
1012
|
+
nothing in `.conformance-recordings/dropbox/<run>/` (gitignored) for manual scrubbing and promotion.
|
|
1013
|
+
|
|
1014
|
+
## Microsoft connector
|
|
1015
|
+
|
|
1016
|
+
```ts
|
|
1017
|
+
import { makeCredentialBinding, makeIntegration } from '@yolk-sdk/connectors'
|
|
1018
|
+
import { MicrosoftConnector, MicrosoftOAuthCredentialSlot } from '@yolk-sdk/connectors/microsoft'
|
|
1019
|
+
|
|
1020
|
+
const integration = makeIntegration({
|
|
1021
|
+
connectorId: 'microsoft',
|
|
1022
|
+
credentialBindings: [
|
|
1023
|
+
makeCredentialBinding({
|
|
1024
|
+
slotId: MicrosoftOAuthCredentialSlot.id,
|
|
1025
|
+
credentialRef: 'microsoft-oauth-credential'
|
|
1026
|
+
})
|
|
1027
|
+
]
|
|
1028
|
+
})
|
|
1029
|
+
|
|
1030
|
+
const mailProgram = MicrosoftConnector.invoke({
|
|
1031
|
+
integration,
|
|
1032
|
+
action: 'outlook.search_messages',
|
|
1033
|
+
input: {
|
|
1034
|
+
query: 'from:alice@example.com',
|
|
1035
|
+
mailbox: 'shared@example.com',
|
|
1036
|
+
top: 10
|
|
1037
|
+
}
|
|
1038
|
+
})
|
|
1039
|
+
|
|
1040
|
+
const filesProgram = MicrosoftConnector.invoke({
|
|
1041
|
+
integration,
|
|
1042
|
+
action: 'onedrive.search_items',
|
|
1043
|
+
input: { query: 'quarterly plan', top: 10 }
|
|
1044
|
+
})
|
|
1045
|
+
```
|
|
1046
|
+
|
|
1047
|
+
This integration targets **Microsoft Outlook, OneDrive, SharePoint sites, and Teams through
|
|
1048
|
+
Microsoft Graph v1.0**. It does not use the retired Outlook REST endpoint, direct Exchange Online APIs, or
|
|
1049
|
+
legacy OneDrive APIs.
|
|
1050
|
+
Microsoft Graph is the shared API and OAuth resource boundary. The sole exception is the
|
|
1051
|
+
pre-authenticated Outlook attachment upload-session URLs that Graph issues to `addOutlookAttachment`,
|
|
1052
|
+
contacted without Authorization.
|
|
1053
|
+
|
|
1054
|
+
All action-scoped slots share the `microsoft.oauth` binding id, so one host credential can serve
|
|
1055
|
+
Outlook and OneDrive when its consent includes the selected actions' `Mail.*` and `Files.*`
|
|
1056
|
+
permissions. Use `MicrosoftCombinedOAuthCredentialSlot` only when broad consent is appropriate.
|
|
1057
|
+
|
|
1058
|
+
Outlook inputs default to the signed-in mailbox (`/me`). Set `mailbox` to a user ID or user principal
|
|
1059
|
+
name to target an Exchange Online shared/delegated mailbox through `/users/{mailbox}`. Signed-in
|
|
1060
|
+
mailbox actions request `Mail.Read`, `Mail.ReadWrite`, or `Mail.Send`. An explicit mailbox that
|
|
1061
|
+
case-insensitively matches `OAuthCredential.accountId` uses those same ordinary slots; other explicit
|
|
1062
|
+
targets request `Mail.Read.Shared`, `Mail.ReadWrite.Shared`, or `Mail.Send.Shared`. Hosts resolve the
|
|
1063
|
+
scope-free identity slot first, then enforce the selected operation slot. Missing identity and bearer
|
|
1064
|
+
credentials do not qualify for the own-mailbox exception. Populate `accountId` with the same Graph
|
|
1065
|
+
user ID or `userPrincipalName` callers pass as `mailbox`: the comparison ignores case only, not
|
|
1066
|
+
whitespace, and does not resolve aliases or equate a user ID with a principal name.
|
|
1067
|
+
|
|
1068
|
+
The signed-in user still needs the relevant Exchange folder/full-access grant. Sending from another
|
|
1069
|
+
mailbox also requires Exchange **Send As** or **Send on Behalf** rights; targeting that mailbox's
|
|
1070
|
+
`/users/{mailbox}` endpoint requires Full Access. For application tokens, set integration config to
|
|
1071
|
+
`{ mailboxAccessMode: 'application' }` and always provide `mailbox`. The connector then uses the non-Shared `Mail.Read`, `Mail.ReadWrite`, and
|
|
1072
|
+
`Mail.Send` application-permission hints. Scope application access to approved mailboxes with host
|
|
1073
|
+
or admin policy, such as Exchange Online RBAC for Applications. Hosts own Entra app registration,
|
|
1074
|
+
tenant/authority selection, OAuth callbacks, refresh, credential storage, and consent.
|
|
1075
|
+
|
|
1076
|
+
`outlook.search_messages` and `outlook.list_messages` accept omitted, `null`, or blank optional
|
|
1077
|
+
string inputs (`mailbox`, `folderId`, `nextLink`, plus list `filter`/`orderBy`) as absent. `top`
|
|
1078
|
+
accepts omission or `null` for the provider default; explicit values must be integers from 1 to 1000. Decoding normalizes these placeholders to `undefined`, while preserving non-blank values
|
|
1079
|
+
unchanged. Search still requires a string `query`, and application access still requires an
|
|
1080
|
+
explicit non-blank `mailbox`. This applies to direct connector calls and generated agent tools.
|
|
1081
|
+
|
|
1082
|
+
Outlook messages report `isRead` plus follow-up flag state as `isFlagged` (`flagged` is true;
|
|
1083
|
+
`notFlagged` and `complete` are false; omitted, null, or unrecognized states assert nothing).
|
|
1084
|
+
`outlook.list_messages` accepts optional `isRead`/`isFlagged` booleans composed into `$filter`
|
|
1085
|
+
with any raw filter (grouped when combined); fresh typed filters cannot be combined with `nextLink`.
|
|
1086
|
+
|
|
1087
|
+
Explicit Outlook batch actions (`outlook.batch_set_read`, `outlook.batch_set_flag`,
|
|
1088
|
+
`outlook.batch_move`, `outlook.batch_trash`, `outlook.batch_untrash`,
|
|
1089
|
+
`outlook.batch_modify_categories`, and the destructive `outlook.delete_permanently`) take 1-100
|
|
1090
|
+
unique nonempty path-safe message IDs plus optional `mailbox` and return complete per-ID outcomes
|
|
1091
|
+
in `messageIds` order with exact counts and sanitized codes only. Execution uses Graph JSON batching
|
|
1092
|
+
(`src/microsoft/mail-batch.ts`) with at most 20 subrequests per sequential envelope, unique correlation IDs, per-subrequest
|
|
1093
|
+
immutable-ID preferences, outer authorization headers only, and responses matched by correlation
|
|
1094
|
+
ID. Move-shaped results report the provider-returned message ID and actual `parentFolderId`
|
|
1095
|
+
(never a fabricated destination); category updates read before PATCHing and leave failed reads
|
|
1096
|
+
`not_attempted`. Permanent deletion POSTs `permanentDelete` (documented 204); items enter
|
|
1097
|
+
Recoverable Items/Purges, so retention or holds may still preserve them.
|
|
1098
|
+
|
|
1099
|
+
Pass Outlook Graph `@odata.nextLink` values back through `nextLink` unchanged. Repeat `mailbox` for
|
|
1100
|
+
an explicit mailbox continuation and `folderId` for a folder continuation. The connector only
|
|
1101
|
+
accepts global Graph v1.0 links for the selected mailbox and folder collection. `outlook.get_message`
|
|
1102
|
+
requests a text body plus required `internetMessageHeaders` (name/value pairs: `List-Unsubscribe`,
|
|
1103
|
+
`References`, and authentication results when the message carries them; an empty array when Graph
|
|
1104
|
+
returns none, as for Sent Items and drafts); list, draft, and mutation actions return the base
|
|
1105
|
+
`OutlookMessage` without headers. Read and draft-returning actions request immutable IDs.
|
|
1106
|
+
|
|
1107
|
+
`outlook.update_draft` (`outlookUpdateDraftAction`, `OutlookUpdateDraftInput`, access `write`)
|
|
1108
|
+
edits an existing draft with `{ messageId, mailbox?, to?, cc?, bcc?, subject?, body?, contentType? }`.
|
|
1109
|
+
At least one editable field is required; `contentType` alone is invalid. Omission preserves a field;
|
|
1110
|
+
empty recipient arrays clear it. `body` is the **complete replacement**, text by default or HTML
|
|
1111
|
+
when explicitly selected, with no prepended quote or rewritten whitespace. Retain any desired
|
|
1112
|
+
quoted history in that replacement. Graph enforces that these fields are draft-only. The SDK
|
|
1113
|
+
issues one PATCH, preserves immutable-ID headers and existing own/shared/application mailbox
|
|
1114
|
+
permission selection, and validates the returned identified draft as `OutlookMessage`. It never
|
|
1115
|
+
sends. Failures after dispatch retain `{ draftId, retryable: false,
|
|
1116
|
+
recovery: 'read_edit_existing_draft' }` in `underlying`, omit retry hints and provider bodies, and
|
|
1117
|
+
require reconciliation of the same draft, not recreation. This operation is not compare-and-swap;
|
|
1118
|
+
update followed by `outlook.send_draft` is not an atomic transaction, and other mailbox clients can
|
|
1119
|
+
change a draft between those requests. Hosts own serialization and review of the full final content.
|
|
1120
|
+
|
|
1121
|
+
`outlook.reply` (`outlookReplyAction`, `OutlookReplyInput`, access `destructive`) sends the
|
|
1122
|
+
complete reviewed reply for an existing message in one Graph `POST .../messages/{id}/reply` with
|
|
1123
|
+
`{ message: { subject, body, toRecipients, ccRecipients, bccRecipients } }`. The original
|
|
1124
|
+
`messageId` plus required `to`/`cc`/`bcc` arrays (explicit, including empty), `subject`, and full
|
|
1125
|
+
`body` travel in that single request: at least one To address is required, no recipient field is
|
|
1126
|
+
left implicit, and no `comment`, `from`, quoted history, subject prefix, recipient inference, or
|
|
1127
|
+
draft round-trip is involved. `body` is the caller's exact string, text by default
|
|
1128
|
+
or HTML when explicitly selected, with whitespace preserved. The `mailbox` selects the authorized
|
|
1129
|
+
`/me` or `/users/{id}` send path with existing own/shared/application send permissions and
|
|
1130
|
+
immutable-ID headers; Graph chooses the sender identity and documents saving replies in Sent
|
|
1131
|
+
Items. Only HTTP 202 Accepted returns `OutlookSendOutput` `{ accepted: true }`. Other HTTP statuses
|
|
1132
|
+
return `outlook_reply_rejected` or `outlook_reply_unknown` failures with
|
|
1133
|
+
`underlying: { outcome: 'rejected' | 'unknown', retryable: false }`. After-dispatch transport
|
|
1134
|
+
failures are typed `ConnectorError`s with the unknown metadata. Neither includes retry hints or
|
|
1135
|
+
provider bodies. Acceptance is submission, not delivery, with no message ID or exactly-once
|
|
1136
|
+
claim. Prefer this over `update_draft` followed by `send_draft` for reviewed replies, since no
|
|
1137
|
+
intermediate mutable draft can change between requests.
|
|
1138
|
+
|
|
1139
|
+
`outlook.create_reply_draft` creates a bodyless reply draft, then prepends the supplied text or HTML
|
|
1140
|
+
to Graph's generated quoted history and saves it. This is a multi-step write: once a draft ID is
|
|
1141
|
+
known, read/save failures retain that ID with reconciliation guidance. Read and edit the existing
|
|
1142
|
+
draft rather than retrying creation; a failed response can follow a successful save. Post-create
|
|
1143
|
+
HTTP failures use `outlook_create_reply_draft_partial`, retain the HTTP `status`, and omit
|
|
1144
|
+
`retryAfterMs` even for a 429. The same partial-failure code covers a read-back without the requested
|
|
1145
|
+
body format; `status` then records the last Graph response and can be 2xx. Branch on the failure
|
|
1146
|
+
code/recovery metadata, not HTTP status alone. Both these failures and post-create typed `ConnectorError`s expose
|
|
1147
|
+
`underlying: { draftId, retryable: false, recovery: 'read_edit_existing_draft' }` once the ID is
|
|
1148
|
+
known. This metadata describes recovery of the whole action, not whether an individual Graph
|
|
1149
|
+
request can later be retried. Hosts must inspect it before any retry policy and use the original
|
|
1150
|
+
`mailbox` when reading/editing the named draft. If the creation response is lost or contains no
|
|
1151
|
+
usable ID, reconcile mailbox state rather than blindly retrying. A text reply converts the quote to
|
|
1152
|
+
text; it does not preserve the quote's original HTML formatting.
|
|
1153
|
+
|
|
1154
|
+
Use `outlook.list_attachments` with a message ID to return an Effect `Chunk` of metadata for file,
|
|
1155
|
+
item, reference, and inline attachments. It accepts `top` and returns an opaque `nextLink`; pass that link back unchanged
|
|
1156
|
+
with the same `messageId` and `mailbox`. Listing selects base attachment properties only, so do not
|
|
1157
|
+
expect `contentId` there; fetch the individual file attachment for `cid:` mapping. Pass a returned file attachment ID to
|
|
1158
|
+
`outlook.get_attachment`; it requires a Graph file attachment with string `contentBytes` (not checked as base64: whoever
|
|
1159
|
+
decodes it validates it) and returns those bytes as required `contentBase64`. Item and reference attachments remain available only
|
|
1160
|
+
as list metadata and are rejected by this action. Both actions use the existing signed-in, shared/delegated, or application `Mail.Read`
|
|
1161
|
+
permission selection. Base64 content remains in the string/JSON HTTP boundary; hosts own decoding,
|
|
1162
|
+
size policy, durable storage, and content scanning. As an agent tool `outlook.get_attachment`
|
|
1163
|
+
resolves to `{ value, files }` instead of base64: `value` is the metadata output, `files` the
|
|
1164
|
+
attachment as a `FileRef` (or `FileUnavailable` when it was not stored).
|
|
1165
|
+
|
|
1166
|
+
To add a file to an existing draft (for example one from `outlook.create_draft` or
|
|
1167
|
+
`outlook.create_reply_draft`) before `outlook.send_draft`, host code calls the host-only
|
|
1168
|
+
`addOutlookAttachment` helper described under [host-only file transfers](#write-guarantees-and-limits).
|
|
1169
|
+
It is deliberately not a connector action, so attachment bytes never enter model tool JSON.
|
|
1170
|
+
|
|
1171
|
+
### Outlook read state, flags, and trash
|
|
1172
|
+
|
|
1173
|
+
- `outlook.set_read` takes `{ messageId, isRead, mailbox? }`: `true` marks read, `false` marks
|
|
1174
|
+
unread using Graph `PATCH` on the message.
|
|
1175
|
+
- `outlook.set_flag` takes `{ messageId, isFlagged, mailbox? }`: `true` flags for follow-up,
|
|
1176
|
+
`false` clears the flag, using Graph `PATCH` `flagStatus`.
|
|
1177
|
+
- `outlook.trash` takes `{ messageId, mailbox? }` and moves the message to `deleteditems` using
|
|
1178
|
+
Graph `/move`; it never performs permanent deletion.
|
|
1179
|
+
- `outlook.untrash` takes `{ messageId, mailbox?, destinationFolderId? }` and moves from Deleted
|
|
1180
|
+
Items to `inbox` by default, or the supplied destination folder ID/well-known name. It does not
|
|
1181
|
+
recover permanently deleted messages or infer the original folder.
|
|
1182
|
+
- `outlook.move_message` takes `{ messageId, mailbox?, destinationFolderId }` with a required
|
|
1183
|
+
destination folder ID/well-known name and moves the message there using Graph `/move`. The source
|
|
1184
|
+
folder is not an input, so the connector performs no same-folder check; Graph decides the outcome.
|
|
1185
|
+
A `deleteditems` destination performs the same Graph call as `outlook.trash`: hosts that gate on
|
|
1186
|
+
declared access should override `move_message` to `destructive` for well-known destructive
|
|
1187
|
+
destinations.
|
|
1188
|
+
|
|
1189
|
+
All five return the provider's updated `OutlookMessage` and request immutable IDs. Use the returned
|
|
1190
|
+
`id` for subsequent calls. They use `Mail.ReadWrite` for the signed-in mailbox/application mode and
|
|
1191
|
+
`Mail.ReadWrite.Shared` for other explicit delegated mailboxes, with the same own-mailbox identity
|
|
1192
|
+
exception and application mailbox guard
|
|
1193
|
+
as draft writes. Read-state, restore, and move actions declare `write`; trash declares `destructive`.
|
|
1194
|
+
|
|
1195
|
+
### Outlook categories
|
|
1196
|
+
|
|
1197
|
+
- `outlook.list_categories` takes `{ mailbox?, top?, nextLink? }` and returns typed
|
|
1198
|
+
`{ categories, nextLink? }` from Graph `/outlook/masterCategories`; `categories` is an Effect
|
|
1199
|
+
`Chunk`. It requires
|
|
1200
|
+
`MailboxSettings.Read` consent.
|
|
1201
|
+
- `outlook.create_category` takes `{ mailbox?, displayName, color? }` where `color` is
|
|
1202
|
+
`none` or `preset0` through `preset24`. It requires `MailboxSettings.ReadWrite` consent.
|
|
1203
|
+
`displayName` is immutable after creation: there is no category rename action because Graph
|
|
1204
|
+
does not support renaming categories, only color updates.
|
|
1205
|
+
- `outlook.delete_category` takes `{ mailbox?, categoryId }` and answers Graph `204` with
|
|
1206
|
+
an empty body, returning typed `{ id, deleted: true }` without JSON decoding. It requires
|
|
1207
|
+
`MailboxSettings.ReadWrite` consent. Existing message assignments keep their category
|
|
1208
|
+
`displayName` strings.
|
|
1209
|
+
- `outlook.get_category` takes `{ mailbox?, categoryId }` and returns the typed category. It
|
|
1210
|
+
requires `MailboxSettings.Read` consent.
|
|
1211
|
+
- `outlook.update_category` takes `{ mailbox?, categoryId, color }` and PATCHes only the color
|
|
1212
|
+
(`displayName` stays immutable). It requires `MailboxSettings.ReadWrite` consent.
|
|
1213
|
+
- `outlook.set_categories` takes `{ messageId, mailbox?, categories }` and replaces the
|
|
1214
|
+
message's category `displayName` strings with Graph `PATCH`; an empty array clears all
|
|
1215
|
+
categories. It reuses the `Mail.ReadWrite` / `Mail.ReadWrite.Shared` message permission
|
|
1216
|
+
selection, own-mailbox identity exception, immutable IDs, and application mailbox guard.
|
|
1217
|
+
- `outlook.modify_categories` takes `{ messageId, mailbox?, addCategories?, removeCategories? }`
|
|
1218
|
+
(at least one of the two) and merges through GET-then-PATCH: removals win over additions and
|
|
1219
|
+
the resulting names are deduped by exact case-sensitive match. Both requests use `Mail.ReadWrite` (or its Shared variant),
|
|
1220
|
+
without requiring separate read consent. The GET requires a valid `categories` array and never defaults
|
|
1221
|
+
omitted or malformed data to `[]`, so a failed or invalid read sends no PATCH. This
|
|
1222
|
+
read/modify/write is non-atomic: hosts must serialize competing updates. There are no
|
|
1223
|
+
retries or implied compare-and-swap.
|
|
1224
|
+
|
|
1225
|
+
Message category assignment uses `displayName` strings, not master category IDs, and never
|
|
1226
|
+
creates or deletes master categories automatically. Master-category lifecycle consent is
|
|
1227
|
+
opt-in through the `MicrosoftOutlookCategoryReadOAuthCredentialSlot` and
|
|
1228
|
+
`MicrosoftOutlookCategoryWriteOAuthCredentialSlot` action slots; the existing combined slot is
|
|
1229
|
+
not widened. There are no `.Shared` mailbox-settings scopes, so delegated access to another
|
|
1230
|
+
mailbox's settings keeps the ordinary category slot and remains subject to Graph
|
|
1231
|
+
authorization. Application mode still requires an explicit `mailbox` for category operations.
|
|
1232
|
+
List continuations must repeat the same mailbox; only global Graph v1.0 links for the selected
|
|
1233
|
+
master-category collection are accepted. Create declares `write`; delete declares `destructive`;
|
|
1234
|
+
set/modify declare `write`.
|
|
1235
|
+
|
|
1236
|
+
Sending returns `{ accepted: true }` for Graph's `202 Accepted`; that confirms submission, not
|
|
1237
|
+
processing or delivery.
|
|
1238
|
+
|
|
1239
|
+
OneDrive actions default to the signed-in user's `/me/drive`; set `driveId` to target
|
|
1240
|
+
`/drives/{driveId}`. Delegated mode uses least-privilege `Files.Read` or `Files.ReadWrite`. Set
|
|
1241
|
+
`oneDriveAccessMode` to `delegated_all` when the host has consented `Files.Read.All` or
|
|
1242
|
+
`Files.ReadWrite.All` for broader delegated access. For application tokens, set it to `application`
|
|
1243
|
+
and always provide `driveId` (the sharing-link and SharePoint actions below need none); application
|
|
1244
|
+
mode also uses the `Files.*.All` slots. List and search continuations must repeat the same drive
|
|
1245
|
+
target; list continuations must also repeat `parentItemId`.
|
|
1246
|
+
|
|
1247
|
+
`onedrive.resolve_sharing_link` resolves a OneDrive or SharePoint sharing link to its item (with
|
|
1248
|
+
`parentReference.driveId`) for this request only, never redeeming it, under `Files.Read.All`
|
|
1249
|
+
(delegated; unverified live for files other people own, since Graph lists `Files.ReadWrite` as least
|
|
1250
|
+
privileged) or `Files.ReadWrite.All` (`application`, no `driveId` needed). `sharepoint.search_sites`
|
|
1251
|
+
and `sharepoint.list_site_drives` find SharePoint document-library drive ids for `driveId`; they use
|
|
1252
|
+
the opt-in `MicrosoftSharePointSitesReadOAuthCredentialSlot` (`Sites.Read.All`), which the combined
|
|
1253
|
+
slot does not include. Delegated hosts reading library items keep `oneDriveAccessMode: 'delegated'`
|
|
1254
|
+
and consent `Files.Read.All` or `Sites.Read.All` as well: Graph honors every scope in the token.
|
|
1255
|
+
|
|
1256
|
+
The `teams.*` actions list and read chats, joined teams, channels, channel posts and replies, send
|
|
1257
|
+
chat messages and channel posts or replies (`destructive`; plain text sent as escaped HTML within
|
|
1258
|
+
`teamsMessageMaxBytes`), find a meeting by its join link and list its transcripts; the host-only
|
|
1259
|
+
`downloadTeamsMeetingTranscript` returns a transcript's WebVTT bytes. Each uses its own opt-in
|
|
1260
|
+
delegated slot (`MicrosoftTeams*OAuthCredentialSlot`, all scopes in `microsoftTeamsScopes`), none
|
|
1261
|
+
in the combined slot; `ChannelMessage.Read.All` and `OnlineMeetingTranscript.Read.All` need tenant
|
|
1262
|
+
admin consent, and Graph supports none of them for personal Microsoft accounts.
|
|
1263
|
+
|
|
1264
|
+
The OneDrive action set lists, searches, and gets file/folder metadata; creates folders; moves items
|
|
1265
|
+
within one drive; queues asynchronous copies; polls copy status; and moves items to the recycle bin.
|
|
1266
|
+
Binary download is available only through the separate host helper below, not the connector action
|
|
1267
|
+
inventory or string/JSON HTTP boundary. Host-only bounded create/update helpers are available below;
|
|
1268
|
+
OneDrive resumable upload sessions remain unimplemented. The built-in Microsoft endpoint targets the
|
|
1269
|
+
global cloud; national-cloud hosts need a cloud-specific connector until the API base is configurable.
|
|
1270
|
+
|
|
1271
|
+
`onedrive.move_item` sends a synchronous `PATCH` with a destination parent ID and optional rename.
|
|
1272
|
+
Graph does not support moving an item between drives through this request, so the action exposes no
|
|
1273
|
+
destination-drive field and never invents copy-then-delete atomicity. An optional `ifMatch` forwards
|
|
1274
|
+
the caller's eTag/cTag precondition; a mismatch returns Graph's `412` failure. Moving to drive root
|
|
1275
|
+
requires the root folder's actual item ID, not the literal `root` alias.
|
|
1276
|
+
|
|
1277
|
+
`onedrive.copy_item` requires destination drive and parent IDs and returns
|
|
1278
|
+
`{ status: 'accepted', monitorUrl }` only after Graph responds `202 Accepted` with one trusted monitor
|
|
1279
|
+
location. **Accepted does not mean completed:** name conflicts and other errors can appear later.
|
|
1280
|
+
Omitting `conflictBehavior` uses Graph's documented `fail` default; `rename` is available for
|
|
1281
|
+
work/school drives, while OneDrive Consumer does not support the conflict query parameter. Destructive
|
|
1282
|
+
`replace` is intentionally not exposed because it deletes the preexisting file and its history, which
|
|
1283
|
+
would make one input mode exceed the action's `write` side-effect classification. Copies create a new
|
|
1284
|
+
item identity, do not retain source metadata or permissions, inherit destination permissions, and copy
|
|
1285
|
+
only the latest major version because version-history copying is not exposed. Graph limits one copy to
|
|
1286
|
+
30,000 drive items. Cross-drive copy is supported by the request shape; app-only cross-geo copy remains
|
|
1287
|
+
unsupported by Graph.
|
|
1288
|
+
|
|
1289
|
+
`onedrive.get_copy_status` performs one poll and returns the provider operation status, optional
|
|
1290
|
+
percentage, completed item ID, or sanitized failure code/message. It rechecks the OneDrive write scope
|
|
1291
|
+
but sends **no authorization header** to the short-lived capability URL. Only canonical raw forms of
|
|
1292
|
+
documented global-cloud `api.onedrive.com` or tenant `*.sharepoint.com` monitor URL shapes are
|
|
1293
|
+
accepted; parser-normalized variants and coalesced locations fail closed. Requests set
|
|
1294
|
+
`redirect: 'manual'` and `credentials: 'omit'`; redirects are never followed. A manual `303` is mapped
|
|
1295
|
+
to `completed` without decoding its body or exposing its `Location`, while rejected monitor responses
|
|
1296
|
+
discard provider bodies. Hosts must treat monitor URLs as secrets, avoid logs/persistence, enforce
|
|
1297
|
+
public DNS/IP policy and TLS, and bound response bodies, timeouts, and total polling. Approval, polling
|
|
1298
|
+
cadence, retries, expiry handling, and reconciliation remain host policy.
|
|
1299
|
+
|
|
1300
|
+
See Microsoft's [Outlook mail API overview](https://learn.microsoft.com/en-us/graph/outlook-mail-concept-overview), [shared/delegated folder guide](https://learn.microsoft.com/en-us/graph/outlook-share-messages-folders), [OneDrive DriveItem overview](https://learn.microsoft.com/en-us/graph/onedrive-concept-overview), [DriveItem move reference](https://learn.microsoft.com/en-us/graph/api/driveitem-move?view=graph-rest-1.0), [DriveItem copy reference](https://learn.microsoft.com/en-us/graph/api/driveitem-copy?view=graph-rest-1.0), [long-running actions guide](https://learn.microsoft.com/en-us/graph/long-running-actions-overview), and [DriveItem addressing guide](https://learn.microsoft.com/en-us/graph/onedrive-addressing-driveitems).
|
|
1301
|
+
|
|
1302
|
+
### Host integration: download OneDrive/SharePoint file bytes
|
|
1303
|
+
|
|
1304
|
+
`downloadOneDriveItem` from `@yolk-sdk/connectors/microsoft` downloads **bytes only**. It is not a
|
|
1305
|
+
connector action and is never automatically serialized by `makeConnectorToolModule`. A host must
|
|
1306
|
+
supply an **app-owned materialization/read tool** to store/scan/extract the bytes and expose bounded,
|
|
1307
|
+
provenance-bearing reader output. A skill can help select drive/item IDs; it cannot itself download
|
|
1308
|
+
or read a file. Search matches/snippets and `get_item` metadata are not full-file contents.
|
|
1309
|
+
|
|
1310
|
+
```ts
|
|
1311
|
+
import { downloadOneDriveItem } from '@yolk-sdk/connectors/microsoft'
|
|
1312
|
+
|
|
1313
|
+
// Host code: provide existing CredentialResolver and a compliant ConnectorBinaryHttpClient layer.
|
|
1314
|
+
// IDs come from discovery. This example assumes host-owned integration and selectedItem values.
|
|
1315
|
+
const download = downloadOneDriveItem(
|
|
1316
|
+
integration,
|
|
1317
|
+
{ itemId: selectedItem.id, driveId: selectedItem.parentReference?.driveId },
|
|
1318
|
+
{ maxBytes: 20 * 1024 * 1024, maxMetadataBytes: 1024 * 1024, maxErrorBodyBytes: 16 * 1024 }
|
|
1319
|
+
)
|
|
1320
|
+
```
|
|
1321
|
+
|
|
1322
|
+
The third argument is trusted **host configuration**, separate from tool parameters. All three
|
|
1323
|
+
nonnegative safe-integer budgets are required; `maxBytes: 0` permits valid empty files. The root
|
|
1324
|
+
exports the additive `ConnectorBinaryHttpClient` port and its request/response/error types; the
|
|
1325
|
+
existing `ConnectorHttpClient` and default `MicrosoftConnector` dependencies are unchanged. The
|
|
1326
|
+
helper uses the binary port for bounded metadata JSON too; only metadata goes through UTF-8 decoding.
|
|
1327
|
+
Office/PDF/content bytes are untouched `Uint8Array`, not text or base64 model content.
|
|
1328
|
+
|
|
1329
|
+
The helper reuses the existing `microsoft.oauth` binding and read-slot selection (`Files.Read`, or
|
|
1330
|
+
`Files.Read.All` for `delegated_all`/`application`). Application access requires an explicit drive.
|
|
1331
|
+
Scopes are permission hints to the existing resolver, not local proof of consent or access; hosts
|
|
1332
|
+
still enforce authorization and token permissions. No new OAuth flow, consent, discovery, workbook
|
|
1333
|
+
API, PDF conversion, native provider document support, or extractor is included.
|
|
1334
|
+
|
|
1335
|
+
Only stable `itemId` and optional `driveId` are accepted. Opaque IDs are encoded once (never decoded
|
|
1336
|
+
as paths); empty/control/space-containing and dot-only IDs are rejected to avoid URL normalization.
|
|
1337
|
+
Metadata `remoteItem` targets require both IDs, with a loop guard and at most four target transitions.
|
|
1338
|
+
Folders/non-files and unresolved remote references fail explicitly. SharePoint files work with a
|
|
1339
|
+
known document-library drive ID; this does not discover SharePoint sites or grant access to them.
|
|
1340
|
+
|
|
1341
|
+
Metadata redirects are rejected. The authenticated Graph `/content` request may follow at most
|
|
1342
|
+
five absolute HTTPS redirects. Every redirected request has **empty headers**, even back to Graph.
|
|
1343
|
+
There is no bearer transfer to `webUrl`, `web_fetch`, or another tool. Userinfo, fragments, unusual
|
|
1344
|
+
ports, malformed/relative URLs, IP literals and obvious local names are rejected syntactically.
|
|
1345
|
+
Preauthenticated URLs and all response headers/bodies are omitted from helper success/error fields.
|
|
1346
|
+
Errors expose only the typed `OneDriveDownloadError.code` (including distinct `unauthorized`,
|
|
1347
|
+
`forbidden`, `not_found`, `rate_limited`, `response_too_large`, and `partial_content`); wrapped
|
|
1348
|
+
credential/transport/provider detail is discarded. Hosts must also avoid logging secrets at the
|
|
1349
|
+
transport boundary. Programmer defects are not converted into safe typed failures.
|
|
1350
|
+
|
|
1351
|
+
**A compliant host adapter is required; the SDK does not implement network I/O.** For _every_ request:
|
|
1352
|
+
|
|
1353
|
+
- Disable automatic redirects, cookie jars and ambient authentication. Honor only explicit headers.
|
|
1354
|
+
Reject duplicate/ambiguous redirect headers instead of silently selecting a destination.
|
|
1355
|
+
- Enforce public-network policy at connection time: resolve/validate all DNS addresses, reject
|
|
1356
|
+
loopback/private/link-local/reserved destinations, and pin/verify the address actually connected
|
|
1357
|
+
to (including redirects, proxies and DNS rebinding). Verify TLS. A hostname syntax check is not
|
|
1358
|
+
SSRF protection; allowed-looking names can resolve to private addresses.
|
|
1359
|
+
- Apply timeouts, Effect interruption/cancellation, connection cleanup, response-header limits,
|
|
1360
|
+
and actual streamed byte limits **before buffering**, including any decompression. Do not trust
|
|
1361
|
+
`Content-Length` or metadata size. These limits are per response, not aggregate transfer quotas.
|
|
1362
|
+
Hosts may impose stricter aggregate/time budgets across the bounded request sequence.
|
|
1363
|
+
- For status 200, cap `maxBytes` and fail with `ConnectorBinaryHttpError` code `response_too_large`
|
|
1364
|
+
on overflow. Return only complete bytes with `bodyComplete: true`. For **every non-200** response,
|
|
1365
|
+
including redirects/206/errors, use the separate `maxErrorBodyBytes` cap; bounded/truncated bodies
|
|
1366
|
+
may use `bodyComplete: false`. Always cancel/close the remainder. The helper checks returned byte
|
|
1367
|
+
length too, rejects incomplete/range-bearing 200 and all 206 responses, and never consumes an
|
|
1368
|
+
error body as a file.
|
|
1369
|
+
|
|
1370
|
+
The result includes `bytes`, actual `byteLength`, the original requested IDs, and allowlisted target
|
|
1371
|
+
`source` fields: available filename/MIME, drive/item identity, HTTPS public-looking browser `webUrl`,
|
|
1372
|
+
provider size, eTag/cTag, and creation/modification timestamps. Missing values remain missing.
|
|
1373
|
+
Metadata size is a hint, not measured length. Metadata was observed **before** downloading; these
|
|
1374
|
+
fields do **not** establish a consistent source snapshot or prove the bytes match a version tag.
|
|
1375
|
+
The helper does not verify hashes, detect file type, parse documents, or prove extraction completeness.
|
|
1376
|
+
Treat filenames/MIME/links as untrusted metadata; use safe host artifact names and validate formats.
|
|
1377
|
+
|
|
1378
|
+
Offline fake-port tests cover protocol flow, byte identity, bounds, status handling and redaction.
|
|
1379
|
+
They do **not** test socket DNS enforcement, streaming cancellation or timeouts. Those adapter tests,
|
|
1380
|
+
app materialization/read tools, extraction/provenance coverage and any live tenant validation remain
|
|
1381
|
+
host work. Do not route the raw result into generic model tool JSON.
|
|
1382
|
+
|
|
1383
|
+
Notion and Todoist actions decode provider wire pagination and expose SDK outputs with camelCase fields such as `nextCursor`. Inputs accept documented camelCase fields and common provider-native snake_case aliases where useful, such as Notion `data_source_id` / `rich_text` and Todoist `project_id` / `task_id` / `filter_lang`.
|
|
1384
|
+
|
|
1385
|
+
LinkedIn email lookup may return `{ status: 'queued', email: null }` when Enrich Layer accepts the lookup asynchronously.
|
|
1386
|
+
|
|
1387
|
+
### Microsoft conformance cases (experimental)
|
|
1388
|
+
|
|
1389
|
+
`@yolk-sdk/connectors/microsoft/conformance` exports eleven conformance cases for
|
|
1390
|
+
`@yolk-sdk/conformance/runner` (`microsoftConformanceCases`), synthetic replay fixtures
|
|
1391
|
+
(`microsoftConformanceFixtures`, `evidence: 'unverified'`), and the seeds they replay with
|
|
1392
|
+
(`microsoftConformanceFixtureSeeds`). Outlook and OneDrive cases run the real connector actions over
|
|
1393
|
+
`ConnectorHttpClient` and `CredentialResolver` plus `MicrosoftConformanceConfig`, which holds
|
|
1394
|
+
host-supplied seed identities in a Microsoft 365 practice tenant. **The connector has no calendar
|
|
1395
|
+
actions yet:** the four calendar cases send raw Graph v1.0 requests through the same ports, token
|
|
1396
|
+
resolution, and Graph failure mapping, and pin expected Graph behaviour (unverified until a live
|
|
1397
|
+
run) for hosts and the Microsoft Graph emulator (`@yolk-sdk/emulators/microsoft`). Credentials bind through `microsoftConformanceIntegration` (`microsoft.oauth`, credential
|
|
1398
|
+
ref `microsoft.conformance`). The case table, seeds, and claims live in the
|
|
1399
|
+
[Microsoft conformance guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/connectors/microsoft.mdx#conformance-cases).
|
|
1400
|
+
|
|
1401
|
+
Every write case creates its own event, recipient-free draft, or folder and registers its id for
|
|
1402
|
+
cleanup before any claim runs (the create and the registration are not interruptible, and the
|
|
1403
|
+
runner sets no request timeout, so a hanging create delays an interruption). When the id
|
|
1404
|
+
is recoverable, the case removes the item again automatically (also after a failed assertion or
|
|
1405
|
+
interruption), verifies the removal where Graph allows it, and fails with
|
|
1406
|
+
`MicrosoftConformanceRestoreFailed` when the removal fails. A create that succeeds without an id also
|
|
1407
|
+
fails with `MicrosoftConformanceRestoreFailed`, and an ambiguous create (a transport or decoding
|
|
1408
|
+
failure, no status, HTTP 408, or HTTP 5xx) fails with `MicrosoftConformanceActionFailed`
|
|
1409
|
+
(`createOutcome: 'unknown'`, code and status kept): both messages advise manual recovery of the
|
|
1410
|
+
`yolk-conformance` item. Each of these (a failed removal, an id-less create, an ambiguous create)
|
|
1411
|
+
raised while the case is being interrupted is also handed, with its full message, to
|
|
1412
|
+
`ConformanceCleanupReporter` (default: `Effect.logWarning`), since the interruption may replace it;
|
|
1413
|
+
an ambiguous create's report starts with the case id. No case sends mail or invitations.
|
|
1414
|
+
`pnpm conformance:microsoft` in this repository dry-runs by default;
|
|
1415
|
+
`--live --owner-approved --account <label>` (refused whenever `CI` is non-empty; with
|
|
1416
|
+
`MICROSOFT_ACCESS_TOKEN` and the seeds) is for owners running a practice tenant by hand (a first
|
|
1417
|
+
Ctrl-C interrupts the run so a running write case still removes its item, and the reports above
|
|
1418
|
+
print on stderr as `WARN` lines; every live-run line is printed with the live access token
|
|
1419
|
+
redacted, as in the shared runners), `--allow-writes reversible` adds the write cases, and `--record`
|
|
1420
|
+
stages verified recordings all or nothing in `.conformance-recordings/microsoft/<run>/` (gitignored)
|
|
1421
|
+
for manual scrubbing and promotion.
|
|
1422
|
+
|
|
1423
|
+
### Notion conformance cases (experimental)
|
|
1424
|
+
|
|
1425
|
+
`@yolk-sdk/connectors/notion/conformance` exports eight conformance cases for
|
|
1426
|
+
`@yolk-sdk/conformance/runner` (`notionConformanceCases`), synthetic replay fixtures
|
|
1427
|
+
(`notionConformanceFixtures`, `evidence: 'unverified'`), and the seeds they replay with
|
|
1428
|
+
(`notionConformanceFixtureSeeds`). Every case runs the real connector actions over
|
|
1429
|
+
`ConnectorHttpClient` and `CredentialResolver` plus `NotionConformanceConfig`, which holds
|
|
1430
|
+
host-supplied seed ids in a practice Notion workspace. They cover search, block children, and page
|
|
1431
|
+
property cursor paging (including the connector's second percent-encoding of property ids), the
|
|
1432
|
+
pinned `Notion-Version`, the `{ object: "error", status, code,
|
|
1433
|
+
message }` envelope, title rich text, the 2025-09-03 database/data source split, and archiving a
|
|
1434
|
+
page to the trash. **Every action sends `Notion-Version: 2025-09-03`**; the pinned-version case
|
|
1435
|
+
observes that header at the `ConnectorHttpClient` port and sends no request of its own. Credentials bind through
|
|
1436
|
+
`notionConformanceIntegration` (`notion.api_token`, credential ref `notion.conformance`). The case
|
|
1437
|
+
table, seeds, and claims live in the
|
|
1438
|
+
[Notion conformance guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/connectors/notion.mdx#conformance-cases).
|
|
1439
|
+
The Notion emulator (`@yolk-sdk/emulators/notion`) passes every case offline.
|
|
1440
|
+
|
|
1441
|
+
The write case creates its own page under the `parentPageId` seed and registers its id before any
|
|
1442
|
+
claim runs (the create and registration are not interruptible, and no request timeout is set, so a
|
|
1443
|
+
hanging create delays an interruption). Any response showing the page trashed (`archived` or
|
|
1444
|
+
`in_trash`), or a not-found read after a successful archive, counts as trashed; otherwise the cleanup
|
|
1445
|
+
trashes the page and checks that `notion.get_page` reports `archived: true`. A failed cleanup fails
|
|
1446
|
+
with `NotionConformanceRestoreFailed`, and an ambiguous create fails with
|
|
1447
|
+
`NotionConformanceActionFailed` (`createOutcome: 'unknown'`) with manual-recovery advice. The live
|
|
1448
|
+
runner turns the first SIGINT/SIGTERM into a fiber interruption, so the cleanup is attempted (not
|
|
1449
|
+
confirmed; a cleanup problem raised meanwhile prints as a WARN line, and the run still ends
|
|
1450
|
+
interrupt-only: exit 130, then the leftover search runs again; duplicate signals within a
|
|
1451
|
+
second are ignored, a later one or a kill skips the cleanup; use `pnpm conformance:notion` or `tsx`
|
|
1452
|
+
directly, not `pnpm exec tsx`, which returns to the prompt at once) and, before the write case,
|
|
1453
|
+
warns about untrashed `yolk-conformance page` pages found by a read-only, bounded (10 search pages),
|
|
1454
|
+
best-effort search (`findNotionConformanceLeftovers`); it never trashes them.
|
|
1455
|
+
`pnpm conformance:notion` in this repository dry-runs by default; `--live --owner-approved --account
|
|
1456
|
+
<label>` (refused whenever `CI` is non-empty; needs `NOTION_API_TOKEN` and the seeds) is for owners
|
|
1457
|
+
running a practice workspace by hand, `--allow-writes reversible` adds the write case, and
|
|
1458
|
+
`--record` stages verified recordings all or nothing in `.conformance-recordings/notion/<run>/`
|
|
1459
|
+
(gitignored) for manual scrubbing and promotion.
|
|
1460
|
+
|
|
1461
|
+
### Todoist conformance cases (experimental)
|
|
1462
|
+
|
|
1463
|
+
`@yolk-sdk/connectors/todoist/conformance` exports seven conformance cases for
|
|
1464
|
+
`@yolk-sdk/conformance/runner` (`todoistConformanceCases`), synthetic replay fixtures
|
|
1465
|
+
(`todoistConformanceFixtures`, `evidence: 'unverified'`), and the seeds they replay with
|
|
1466
|
+
(`todoistConformanceFixtureSeeds`). Every case runs the real connector actions over
|
|
1467
|
+
`ConnectorHttpClient` and `CredentialResolver` plus `TodoistConformanceConfig`, which holds
|
|
1468
|
+
host-supplied seed ids in a practice Todoist account. They cover filtered task list cursor paging,
|
|
1469
|
+
the HTTP 404 error body, task labels as label names, the create/get/update/close task lifecycle
|
|
1470
|
+
(a closed task leaves the active list), `due_date` / `due_datetime` as the connector sends them
|
|
1471
|
+
answering a due dated 2030-01-15 (its representation unchecked), project `parent_id`, and delete then
|
|
1472
|
+
not-found. Credentials bind through `todoistConformanceIntegration` (`todoist.api_token`, credential
|
|
1473
|
+
ref `todoist.conformance`). The case table, seeds, and claims live in the
|
|
1474
|
+
[Todoist conformance guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/connectors/todoist.mdx#conformance-cases).
|
|
1475
|
+
|
|
1476
|
+
Every write case creates its own `yolk-conformance-<runId>-<case>` project under the
|
|
1477
|
+
`workProjectId` seed and works only inside it. The `runId` seed makes that namespace unique per
|
|
1478
|
+
invocation (the fixtures replay with `run-synthetic`; the live runner generates a fresh random id
|
|
1479
|
+
every time). The project create, its decoding, and the id registration are not interruptible, and
|
|
1480
|
+
neither is any later write. A definitive create rejection (HTTP 4xx other than 408) deletes
|
|
1481
|
+
nothing; an ambiguous create (a transport or decoding failure, no status, HTTP 408, or HTTP 5xx)
|
|
1482
|
+
fails with
|
|
1483
|
+
`TodoistConformanceActionFailed` (`createOutcome: 'unknown'`) naming the exact project or task to
|
|
1484
|
+
check by hand, and nothing is deleted by name. After a successful create, the cleanup deletes the
|
|
1485
|
+
project by id (also after a failed assertion or an interruption) and checks that
|
|
1486
|
+
`todoist.get_project` answers not found; a failed cleanup fails with
|
|
1487
|
+
`TodoistConformanceRestoreFailed` naming the project and id, and a project without the requested
|
|
1488
|
+
name or with a seeded project's id, or a task outside the case project, is never deleted
|
|
1489
|
+
(`TodoistConformanceCleanupRefused`). The cleanup verifies only that the project is gone; that its
|
|
1490
|
+
tasks go with it is the delete case's unverified claim.
|
|
1491
|
+
Before any write case, and again after an interrupt-only exit (130), the runner warns read-only
|
|
1492
|
+
about `yolk-conformance-run-*` projects earlier runs left behind
|
|
1493
|
+
(`findTodoistConformanceLeftovers`, bounded to 20 listing pages); it never deletes them.
|
|
1494
|
+
`pnpm conformance:todoist` in this repository dry-runs by default; `--live --owner-approved
|
|
1495
|
+
--account <label>` (refused whenever `CI` is non-empty; needs `TODOIST_API_TOKEN` and the seeds) is
|
|
1496
|
+
for owners running a practice account by hand, `--allow-writes reversible` adds the write cases, and
|
|
1497
|
+
`--record` stages verified recordings all or nothing in `.conformance-recordings/todoist/<run>/`
|
|
1498
|
+
(gitignored) for manual scrubbing and promotion.
|
|
1499
|
+
For offline tests, the experimental Todoist emulator (`@yolk-sdk/emulators/todoist`) is a
|
|
1500
|
+
stateful, fixture-only stand-in that passes these cases; it does not emulate the leftover lookup's
|
|
1501
|
+
project listing (no fixture records it), so that lookup fails closed against it.
|
|
1502
|
+
|
|
1503
|
+
### Telegram conformance cases (experimental)
|
|
1504
|
+
|
|
1505
|
+
`@yolk-sdk/connectors/telegram/conformance` exports four conformance cases for
|
|
1506
|
+
`@yolk-sdk/conformance/runner` (`telegramConformanceCases`), synthetic replay fixtures
|
|
1507
|
+
(`telegramConformanceFixtures`, `evidence: 'unverified'`, whose URLs carry the synthetic
|
|
1508
|
+
`telegramConformanceReplayBotToken`), and the seeds they replay with
|
|
1509
|
+
(`telegramConformanceFixtureSeeds`). Every case runs the real connector actions, or the host-only
|
|
1510
|
+
`downloadTelegramFile`, over `ConnectorHttpClient`, `ConnectorBinaryHttpClient`, and
|
|
1511
|
+
`CredentialResolver` plus `TelegramConformanceConfig` (a practice chat id, a file id, and the run
|
|
1512
|
+
id). The Telegram actions read only HTTP statuses, so claims about the Bot API `ok` field are
|
|
1513
|
+
observed at those ports; the host-only `downloadTelegramFile` decodes the `getFile` result. They
|
|
1514
|
+
cover `telegram.validate` (one `getChat`, not `getMe`), errors as a 4xx status with `ok: false`
|
|
1515
|
+
(never `200` with `ok: false`), `getFile` for downloads (the seeded file must report a size), and
|
|
1516
|
+
`telegram.send_message`. Credentials bind through `telegramConformanceIntegration(chatId)`
|
|
1517
|
+
(`telegram.bot_token`, credential ref `telegram.conformance`). The case table, seeds, and claims
|
|
1518
|
+
live in the
|
|
1519
|
+
[Telegram conformance guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/connectors/telegram.mdx#conformance-cases).
|
|
1520
|
+
|
|
1521
|
+
**The send case is write-irreversible:** it posts a real message naming the run id to the seeded
|
|
1522
|
+
chat, and the connector cannot delete it. It never runs under `allowWrites: 'reversible'`; a runner
|
|
1523
|
+
starts it only when a person names its exact id (`allowIrreversible`, or the live runner's
|
|
1524
|
+
`--allow-irreversible telegram.messages.send-message`). The send is not interruptible; a definitive
|
|
1525
|
+
rejection (4xx other than 408; 429 included) sent nothing, and an ambiguous send (a transport or
|
|
1526
|
+
decoding failure, no status, HTTP 408 or 5xx, or a 2xx whose body lacks `ok: true`) fails with
|
|
1527
|
+
`TelegramConformanceActionFailed` (`sendOutcome: 'unknown'`) naming the exact text to look for in
|
|
1528
|
+
the chat, also through `ConformanceCleanupReporter` when the case is being interrupted. There is
|
|
1529
|
+
nothing to clean up and no leftover lookup; the live runner prints the run id when the send is
|
|
1530
|
+
enabled.
|
|
1531
|
+
`pnpm conformance:telegram` in this repository dry-runs by default; `--live --owner-approved
|
|
1532
|
+
--account <label>` (refused whenever `CI` is non-empty; needs `TELEGRAM_BOT_TOKEN` and the seeds) is
|
|
1533
|
+
for owners running a practice bot by hand, and `--record` replaces the live bot token with the
|
|
1534
|
+
replay token in every recorded URL, then refuses to stage or print a checklist for any recording in
|
|
1535
|
+
which the token or its secret part survives anywhere (URLs, headers, decoded base64 bodies,
|
|
1536
|
+
reassembled stream chunks, unescaped JSON strings; raw, percent-encoded, escaped, or
|
|
1537
|
+
base64-encoded) or that holds a body outside the inspectable allowlist (strict UTF-8 text without NUL
|
|
1538
|
+
characters: binary, compressed, and UTF-16 bodies are refused, so the `fileId` seed must be a plain
|
|
1539
|
+
UTF-8 text file), and stages verified recordings all or nothing in
|
|
1540
|
+
`.conformance-recordings/telegram/<run>/` (gitignored) for manual scrubbing and promotion.
|
|
1541
|
+
For offline tests, the experimental Telegram emulator (`@yolk-sdk/emulators/telegram`) is a
|
|
1542
|
+
stateful, fixture-only stand-in that passes these cases, records the send in its state, and never
|
|
1543
|
+
keeps or echoes the bot token.
|
|
1544
|
+
|
|
1545
|
+
### GitHub conformance cases (experimental)
|
|
1546
|
+
|
|
1547
|
+
`@yolk-sdk/connectors/github/conformance` exports seven conformance cases for
|
|
1548
|
+
`@yolk-sdk/conformance/runner` (`githubConformanceCases`), synthetic replay fixtures
|
|
1549
|
+
(`githubConformanceFixtures`, `evidence: 'unverified'`), and the seeds they replay with
|
|
1550
|
+
(`githubConformanceFixtureSeeds`). Every case runs the real connector actions over
|
|
1551
|
+
`ConnectorHttpClient` and `CredentialResolver` plus `GithubConformanceConfig`, which holds the
|
|
1552
|
+
practice repository's `owner` and `repo` and a few seeded items. They cover label list paging
|
|
1553
|
+
through `Link` `rel="next"`, the 404 and 422 error envelopes the connector maps, base64 file
|
|
1554
|
+
contents, a comment created and deleted by id, a label added and removed, and the issue
|
|
1555
|
+
create/get/update/close lifecycle. Credentials bind through `githubConformanceIntegration(owner, repo)`
|
|
1556
|
+
(`github.token`, credential ref `github.conformance`). The case table, seeds, and claims live in the
|
|
1557
|
+
[GitHub conformance guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/connectors/github.mdx#conformance-cases).
|
|
1558
|
+
|
|
1559
|
+
Every write names the invocation-unique `runId` (the fixtures replay with `run-synthetic`; the live
|
|
1560
|
+
runner generates a fresh random id every time) or touches only the seeded work issue and label. The
|
|
1561
|
+
create, its decoding, and its registration are not interruptible, and neither is any later write.
|
|
1562
|
+
A definitive rejection (HTTP 4xx other than 408) undoes nothing; an ambiguous write (a transport or
|
|
1563
|
+
decoding failure, no status, HTTP 408, or HTTP 5xx) fails with `GithubConformanceActionFailed`
|
|
1564
|
+
(`writeOutcome: 'unknown'`) naming the exact item; an answer outside the run namespace is never
|
|
1565
|
+
adopted (`GithubConformanceCleanupRefused`). The comment and label cases are write-reversible: the
|
|
1566
|
+
cleanup deletes the comment by id or removes the label, verifies it, and fails with
|
|
1567
|
+
`GithubConformanceRestoreFailed` when that fails. They cannot undo what they trigger (the comment
|
|
1568
|
+
notifies the work issue's subscribers; the label add and remove stay on its timeline), so the work
|
|
1569
|
+
issue must be a practice issue nobody else watches. **The issue lifecycle case is
|
|
1570
|
+
write-irreversible:** GitHub issues cannot be deleted through the REST API, so the issue it opens
|
|
1571
|
+
stays in the repository, closed; it runs only when a person names its exact id
|
|
1572
|
+
(`--allow-irreversible github.issues.lifecycle-close`). Before any write case, and again after an
|
|
1573
|
+
interrupt-only exit, the runner warns read-only about open `yolk-conformance run-*` issues, run
|
|
1574
|
+
comments on the work issue, and the seeded label on it (`findGithubConformanceLeftovers`).
|
|
1575
|
+
`pnpm conformance:github` in this repository dry-runs by default; `--live --owner-approved
|
|
1576
|
+
--account <label>` (refused whenever `CI` is non-empty; needs `GITHUB_TOKEN` and the seeds) is for
|
|
1577
|
+
owners running a practice repository by hand, `--allow-writes reversible` adds the comment and
|
|
1578
|
+
label cases, and `--record` keeps the `link` response header, refuses any recording in which the
|
|
1579
|
+
token survives, and stages verified recordings all or nothing in
|
|
1580
|
+
`.conformance-recordings/github/<run>/` (gitignored) for manual scrubbing and promotion.
|
|
1581
|
+
For offline tests, the experimental GitHub emulator (`@yolk-sdk/emulators/github`) is a stateful,
|
|
1582
|
+
fixture-only stand-in that passes these cases; it does not emulate the leftover lookup's open-issue
|
|
1583
|
+
listing (no fixture records it), so that lookup fails closed against it.
|
|
1584
|
+
|
|
1585
|
+
### Google conformance cases (experimental)
|
|
1586
|
+
|
|
1587
|
+
`@yolk-sdk/connectors/google/conformance` exports fifteen conformance cases for
|
|
1588
|
+
`@yolk-sdk/conformance/runner` (`googleConformanceCases`), synthetic replay fixtures
|
|
1589
|
+
(`googleConformanceFixtures`, `evidence: 'unverified'`), and the seeds they replay with
|
|
1590
|
+
(`googleConformanceFixtureSeeds`). Every case runs the real Gmail, Calendar, and Drive actions over
|
|
1591
|
+
`ConnectorHttpClient` and `CredentialResolver` plus `GoogleConformanceConfig`, which holds a
|
|
1592
|
+
practice mailbox address, practice messages and a label, a practice calendar and time range, and a
|
|
1593
|
+
practice Drive folder and file. They cover `gmail.list` and `gmail.list_threads` paging through
|
|
1594
|
+
`nextPageToken` (the thread listing naming exactly the threads of the label's messages), base64url
|
|
1595
|
+
attachment data, the 404 error envelope, a `metadataHeaders` selection on `gmail.get_message` and
|
|
1596
|
+
`gmail.get_thread`, a label created, applied, and deleted, a draft composed, updated, and deleted,
|
|
1597
|
+
trash and untrash, a send to the practice address, Calendar range paging, an event lifecycle and its
|
|
1598
|
+
deleted state, Drive folder paging, the `get_file` field selection, and a folder trashed and
|
|
1599
|
+
deleted. Credentials bind through `googleConformanceIntegration` (`google.oauth`, credential ref
|
|
1600
|
+
`google.conformance`). The case table, seeds, and claims live in the
|
|
1601
|
+
[Google conformance guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/connectors/google.mdx#conformance-cases).
|
|
1602
|
+
|
|
1603
|
+
Every write names the invocation-unique `runId` (the fixtures replay with `run-synthetic`; the live
|
|
1604
|
+
runner generates a fresh random id every time) or touches only the seeded work message. The create,
|
|
1605
|
+
its decoding, and its registration are not interruptible, and neither is any later write. A
|
|
1606
|
+
definitive rejection (HTTP 4xx other than 408) undoes nothing; an ambiguous write fails with
|
|
1607
|
+
`GoogleConformanceActionFailed` (`writeOutcome: 'unknown'`) naming the exact item; an answer the
|
|
1608
|
+
case cannot prove is its own (for a draft, a metadata read of its message: `DRAFT`, the run subject,
|
|
1609
|
+
no recipient) is never adopted, updated, or deleted (`GoogleConformanceCleanupRefused`). The label, draft, trash,
|
|
1610
|
+
event, and folder cases are write-reversible: the cleanup undoes by id, verifies, and fails with
|
|
1611
|
+
`GoogleConformanceRestoreFailed` when that fails. Events never have attendees (no invitation is ever
|
|
1612
|
+
sent), drafts never have recipients, and the folder case trashes its folder and then deletes it
|
|
1613
|
+
permanently, so nothing stays in Drive Trash. **The send case is write-irreversible:** Gmail cannot
|
|
1614
|
+
unsend; it sends one message whose only recipient is the seeded practice address, and runs only
|
|
1615
|
+
when a person names its exact id (`--allow-irreversible google.gmail.send-practice-address`).
|
|
1616
|
+
`practiceAddress` and `runId` are branded seed types (`GooglePracticeAddress`,
|
|
1617
|
+
`GoogleConformanceRunId`), and every case decodes the seeds it reads again before any request, so
|
|
1618
|
+
a list, display name, header injection, or control character fails a precondition and sends
|
|
1619
|
+
nothing, whether or not the host went through the runner.
|
|
1620
|
+
Before any write case, and again after an interrupt-only exit, the runner warns read-only about run
|
|
1621
|
+
labels and drafts, the work message in Trash, run events, and run Drive items
|
|
1622
|
+
(`findGoogleConformanceLeftovers`). `pnpm conformance:google` in this repository dry-runs by
|
|
1623
|
+
default; `--live --owner-approved --account <label>` (refused whenever `CI` is non-empty; needs
|
|
1624
|
+
`GOOGLE_ACCESS_TOKEN`, refused before any request unless it looks like `ya29.…`, and the seeds) is
|
|
1625
|
+
for owners running a practice account by hand, `--allow-writes reversible` adds the reversible
|
|
1626
|
+
cases, and `--record` refuses any recording in which the token survives and stages verified
|
|
1627
|
+
recordings all or nothing in `.conformance-recordings/google/<run>/` (gitignored) for manual
|
|
1628
|
+
scrubbing and promotion.
|
|
1629
|
+
For offline tests, the experimental Google emulator (`@yolk-sdk/emulators/google`) is a stateful,
|
|
1630
|
+
fixture-only stand-in that passes these cases, records the practice send in its state (never
|
|
1631
|
+
delivering it), and never keeps or echoes the access token; no fixture records the leftover
|
|
1632
|
+
lookup's reads, so that lookup fails closed against it.
|
|
1633
|
+
|
|
1634
|
+
### LinkedIn search conformance cases (experimental)
|
|
1635
|
+
|
|
1636
|
+
`@yolk-sdk/connectors/linkedin-search/conformance` exports seven conformance cases for
|
|
1637
|
+
`@yolk-sdk/conformance/runner` (`linkedInSearchConformanceCases`), synthetic replay fixtures
|
|
1638
|
+
(`linkedInSearchConformanceFixtures`, `evidence: 'unverified'`), and the seeds they replay with
|
|
1639
|
+
(`linkedInSearchConformanceFixtureSeeds`). Every case runs the real connector actions over
|
|
1640
|
+
`ConnectorHttpClient` and `CredentialResolver` plus `LinkedInSearchConformanceConfig` (an Exa people
|
|
1641
|
+
query, a profile URL, and a profile URL that names no profile), and every case is a read. They cover
|
|
1642
|
+
Exa people results (1 to 10, each with a `url`, no `null` field the connector decodes), the
|
|
1643
|
+
`numResults` limit (a control search with `numResults: 3` must answer more than 2 people first; no
|
|
1644
|
+
paging exists), the Enrich Layer profile answered as a non-empty object, the email lookup answering
|
|
1645
|
+
an `email` or a queued `email_queue_count` with the connector never reporting `status: "unknown"`,
|
|
1646
|
+
an unknown key at each provider answering a 4xx status, and a missing profile answering a 4xx status
|
|
1647
|
+
rather than an empty 2xx profile. Rate limiting is not a case: the connector maps a 429 like any
|
|
1648
|
+
other non-2xx answer and reads no `Retry-After`. Credentials bind through
|
|
1649
|
+
`linkedInSearchConformanceIntegration()` (both API key slots);
|
|
1650
|
+
`linkedInSearchConformanceCredentials` keys the two keys by slot id for
|
|
1651
|
+
`staticCredentialResolverLayer`. Every 2xx fixture body keeps only the keys and types its case
|
|
1652
|
+
reads, and a strict allowlist test (`test/linkedin-search-conformance.test.ts`, whose comment lists
|
|
1653
|
+
exactly what it enforces) refuses anything in a 2xx body, request query, or seed that is not
|
|
1654
|
+
obviously synthetic. The case table, seeds, and claims live in the
|
|
1655
|
+
[LinkedIn search conformance guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/connectors/linkedin-search.mdx#conformance-cases).
|
|
1656
|
+
For offline tests, the experimental LinkedIn search emulator
|
|
1657
|
+
(`@yolk-sdk/emulators/linkedin-search`) is a stateful, fixture-only stand-in for the Exa and Enrich
|
|
1658
|
+
Layer routes that passes these cases, answering each from a fixture byte for byte (the recorded 401
|
|
1659
|
+
for a key its seed marks as rejected on that provider), and never keeps or echoes an API key.
|
|
1660
|
+
|
|
1661
|
+
`pnpm conformance:linkedin-search` in this repository dry-runs by default;
|
|
1662
|
+
`--live --owner-approved --account <label>` (refused whenever `CI` is non-empty) needs
|
|
1663
|
+
`EXA_API_KEY` and `ENRICH_LAYER_API_KEY` from the environment only (each refused before any
|
|
1664
|
+
request unless it has 16 to 256 letters, digits, `_`, or `-`) and the seeds, with `linkedin.com`
|
|
1665
|
+
profile URLs. Neither provider has a sandbox: the keys are real, paid keys (use dedicated
|
|
1666
|
+
low-credit ones), and `--profile-url` should name a profile whose owner consented, for example the
|
|
1667
|
+
repository owner's own; a run needs the owner's approval although nothing is written. Every
|
|
1668
|
+
printed line is redacted of both keys, and `--record` refuses any recording, rendered file, or
|
|
1669
|
+
checklist line carrying either one (naming which) and stages verified recordings all or nothing in
|
|
1670
|
+
`.conformance-recordings/linkedin-search/<run>/` (gitignored), listing every string value they hold
|
|
1671
|
+
for review. **They hold real third parties' personal data, and this repository is public:** before
|
|
1672
|
+
promoting, replace each recorded 2xx body wholesale with a minimal synthetic body that keeps only
|
|
1673
|
+
the keys and types the case reads, never scrubbing field by field.
|
|
1674
|
+
|
|
1675
|
+
### R2 conformance cases (experimental)
|
|
1676
|
+
|
|
1677
|
+
`@yolk-sdk/connectors/r2-storage/conformance` exports six port-level conformance cases
|
|
1678
|
+
(`r2ConformanceCases`), synthetic `PortFixture`s (`r2ConformanceFixtures`), and the seeds they
|
|
1679
|
+
replay with (`r2ConformanceFixtureSeeds`). The connector never talks to R2 itself: the cases run
|
|
1680
|
+
`r2_storage.upload_url` over the host `R2Presigner` and `getR2Object` / `createR2Object` /
|
|
1681
|
+
`updateR2Object` over the host `R2ObjectClient`, plus `CredentialResolver` and
|
|
1682
|
+
`R2ConformanceConfig`. They cover the presigned PUT URL (bucket and key, SigV4 parameters, an expiry
|
|
1683
|
+
within the SigV4 limit, the signed content type, and a credential for the access key id the
|
|
1684
|
+
connector passed), `maxBytes` and `expectedEtag` on get, a missing key, an absent-only create, and
|
|
1685
|
+
an `If-Match` update. `r2PortsLayerFromBackend` bridges a plain-JSON backend to both ports without
|
|
1686
|
+
ever handing it the credentials, and `makeR2ReplayBackend` replays the fixtures. The two write cases
|
|
1687
|
+
are **write-irreversible** (the connector cannot delete R2 objects): they write only under
|
|
1688
|
+
`yolk-conformance/<runId>/` and report an ambiguous put with the exact bucket and key; a live host
|
|
1689
|
+
must generate a fresh `run-<hex>` per invocation. Presigned URLs in fixtures carry only synthetic
|
|
1690
|
+
credential placeholders: run both `scanPortFixtureForSecrets` and `findR2PortFixtureSecrets`
|
|
1691
|
+
(fail-closed: any credential name outside an exact canonical placeholder occurrence, in any letter
|
|
1692
|
+
case, raw or percent-, JSON-, `\x`-, or HTML-escape-decoded up to the stated depth);
|
|
1693
|
+
`scrubR2PortFixture` rewrites live ones except escaped URLs, so rerun both scans after it. The
|
|
1694
|
+
fixture-driven fake in `@yolk-sdk/emulators/r2` plugs into `r2PortsLayerFromBackend` the same way
|
|
1695
|
+
(connectors never depend on emulators). Live verification needs a host implementation of both ports;
|
|
1696
|
+
no live R2 runner ships. The case table lives in the
|
|
1697
|
+
[R2 conformance guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/connectors/r2-storage.mdx#conformance-cases).
|
|
1698
|
+
|
|
1699
|
+
## Host-only file capabilities
|
|
1700
|
+
|
|
1701
|
+
New byte helpers are separate from connector actions and generic agent serialization. They use
|
|
1702
|
+
root `ConnectorFileTransferBudget` (`maxBytes`, `maxMetadataBytes`, `maxErrorBodyBytes`) and fail
|
|
1703
|
+
with `ConnectorFileTransferError` carrying only `code` plus an optional HTTP `status` number. Existing Dropbox/OneDrive download APIs and all
|
|
1704
|
+
base64 attachment actions remain unchanged. Full API/policy reference:
|
|
1705
|
+
[Transfer connector files](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/connectors/files.mdx).
|
|
1706
|
+
|
|
1707
|
+
| Subpath | Retrieval helpers | Create/update helpers |
|
|
1708
|
+
| ------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
|
|
1709
|
+
| `dropbox` | `downloadDropboxFile` | `createDropboxFile`, `updateDropboxFile` |
|
|
1710
|
+
| `microsoft` | `downloadOneDriveItem`, `downloadOutlookAttachment` | `createOneDriveFile`, `updateOneDriveFile`, `addOutlookAttachment` |
|
|
1711
|
+
| `r2-storage` | `getR2Object` | `createR2Object`, `updateR2Object` |
|
|
1712
|
+
| `google` | `downloadGoogleDriveFile`, `exportGoogleDriveFile`, `downloadGmailAttachment` | Not added |
|
|
1713
|
+
| `fortnox` | `downloadFortnoxInvoicePreview`, `downloadFortnoxOfferPreview`, `downloadFortnoxArchiveFile`, `downloadFortnoxInboxFile` | `uploadFortnoxInboxFile` |
|
|
1714
|
+
| `notion` | `downloadNotionFile` | Not added |
|
|
1715
|
+
| `email` | `downloadEmailAttachment` | Not added |
|
|
1716
|
+
| `telegram` | `downloadTelegramFile` | Not added |
|
|
1717
|
+
| `todoist` | `downloadTodoistAttachment` | Not added |
|
|
1718
|
+
| `github` | Not added | `uploadGithubAttachment` |
|
|
1719
|
+
|
|
1720
|
+
Host integration fragment (approval, integration, transport layers and runtime omitted):
|
|
1721
|
+
|
|
1722
|
+
```ts
|
|
1723
|
+
import { createDropboxFile, updateDropboxFile } from '@yolk-sdk/connectors/dropbox'
|
|
1724
|
+
import { updateOneDriveFile } from '@yolk-sdk/connectors/microsoft'
|
|
1725
|
+
import { downloadGoogleDriveFile } from '@yolk-sdk/connectors/google'
|
|
1726
|
+
|
|
1727
|
+
const budget = { maxBytes: 20_000_000, maxMetadataBytes: 1_000_000, maxErrorBodyBytes: 16_384 }
|
|
1728
|
+
const create = createDropboxFile(dropboxIntegration, { path: '/new.pdf', bytes }, budget)
|
|
1729
|
+
const update = updateDropboxFile(
|
|
1730
|
+
dropboxIntegration,
|
|
1731
|
+
{ fileId: 'id:host-dropbox-file-id', expectedRev, bytes },
|
|
1732
|
+
budget
|
|
1733
|
+
)
|
|
1734
|
+
const replace = updateOneDriveFile(
|
|
1735
|
+
microsoftIntegration,
|
|
1736
|
+
{ itemId, driveId, bytes, acknowledgeOverwrite: true },
|
|
1737
|
+
budget
|
|
1738
|
+
)
|
|
1739
|
+
const download = downloadGoogleDriveFile(googleIntegration, { fileId: driveFileId }, budget)
|
|
1740
|
+
// Provide host services, run the Effect, then store/scan/extract bytes outside model/tool JSON.
|
|
1741
|
+
```
|
|
1742
|
+
|
|
1743
|
+
### Write guarantees and limits
|
|
1744
|
+
|
|
1745
|
+
`ConnectorBinaryWriteHttpClient` is a new optional root service, independent of the unchanged
|
|
1746
|
+
GET-only `ConnectorBinaryHttpClient`. Requests carry `Uint8Array`, `maxUploadBytes`, successful
|
|
1747
|
+
metadata `maxBytes`, `maxErrorBodyBytes`, `successStatuses: [200, 201]`, `redirect: 'manual'` and
|
|
1748
|
+
`credentials: 'omit'`. Only complete HTTP 200/201 metadata is accepted; redirects never replay writes.
|
|
1749
|
+
The optional `uploadSession` method (request type `ConnectorBinaryUploadSessionRequest`) sends
|
|
1750
|
+
`PUT` ranges or a `DELETE` cancellation to a provider-issued, pre-authenticated upload-session URL.
|
|
1751
|
+
Existing adapters without it still compile; helpers that need it fail `upload_session_required`
|
|
1752
|
+
before credentials or network, including when no binary write port is provided at all. Outlook
|
|
1753
|
+
draft attachments use this port only for session ranges: their authenticated Graph JSON POSTs
|
|
1754
|
+
(`fileAttachment`, `createUploadSession`) travel over `ConnectorHttpClient`, whose host adapter
|
|
1755
|
+
must allow those Graph POSTs and a success body of `maxMetadataBytes` plus the echoed base64 content
|
|
1756
|
+
(about 4 MiB for a file just under 3 MiB), and must not log, trace or persist those request or
|
|
1757
|
+
response bodies (file content and the token-bearing `uploadUrl`). The helper never reads their error
|
|
1758
|
+
bodies; cap oversized ones without failing so the status still maps. Hosts implementing `uploadSession`
|
|
1759
|
+
must allowlist the origin and path shape (Outlook: `https://outlook.office.com/api/{v1.0,v2.0,gv1.0,beta}/.../AttachmentSessions(...)` only), send the URL
|
|
1760
|
+
unchanged with no Authorization/cookies/ambient credentials, never log/trace/persist the URL (it
|
|
1761
|
+
embeds an auth token) or bodies, follow no redirects, never retry, apply the same TLS, DNS/socket,
|
|
1762
|
+
timeout, cancellation and streamed limits as `request`, and return response headers including
|
|
1763
|
+
`Location` on a final 201.
|
|
1764
|
+
|
|
1765
|
+
- Dropbox uses `files.content.write`. Create is strict `add`; update requires stable `id:` and
|
|
1766
|
+
a concrete revision with `mode: update`. Both enforce `strict_conflict: true`, `autorename: false`;
|
|
1767
|
+
stale or deleted updates cannot become creates. Single-upload cap: **150,000,000 bytes**.
|
|
1768
|
+
- OneDrive create takes `{ parentItemId, name, driveId?, bytes }` and sends conflict behavior `fail`.
|
|
1769
|
+
Update takes `{ itemId, driveId?, bytes, acknowledgeOverwrite: true }` and replaces unconditionally.
|
|
1770
|
+
**Acknowledgement is not CAS: concurrent edits can be overwritten.** No simple-upload `If-Match`
|
|
1771
|
+
guarantee is invented. Require informed host overwrite approval or decline when CAS is required.
|
|
1772
|
+
Write permission/application-drive guards match metadata writes. Cap: **250,000,000 bytes**.
|
|
1773
|
+
- `addOutlookAttachment` takes `{ messageId, name, contentType, bytes, mailbox? }` and attaches one
|
|
1774
|
+
file to an existing Outlook **draft**; it never sends. It reuses Outlook write-slot selection
|
|
1775
|
+
(`Mail.ReadWrite`, `Mail.ReadWrite.Shared` for delegated non-own mailboxes, application mailbox
|
|
1776
|
+
guard). Files under 3 MiB (`outlookAttachmentSingleRequestMaxBytes`) use one Graph `POST
|
|
1777
|
+
/messages/{id}/attachments` `#microsoft.graph.fileAttachment`; the success metadata budget is
|
|
1778
|
+
`maxMetadataBytes` plus the echoed base64 length. 3 MiB through 150 MiB
|
|
1779
|
+
(`outlookAttachmentUploadSessionMaxBytes`) use `POST .../attachments/createUploadSession`
|
|
1780
|
+
(bounded by `maxMetadataBytes`). Both authenticated Graph POSTs go through the regular
|
|
1781
|
+
`ConnectorHttpClient` as ASCII-only JSON string bodies with the Outlook Bearer, JSON
|
|
1782
|
+
accept/content-type and `Prefer: IdType="ImmutableId"` headers, `redirect: 'manual'` and
|
|
1783
|
+
`credentials: 'omit'`; the helper requires `CredentialResolver | ConnectorHttpClient` only.
|
|
1784
|
+
`ConnectorBinaryWriteHttpClient` is read optionally and used only for session ranges, so hosts
|
|
1785
|
+
without any binary write port can still attach files under 3 MiB. Session uploads then send
|
|
1786
|
+
sequential 3,932,160-byte (12 x 320 KiB) `PUT` ranges through `uploadSession` with
|
|
1787
|
+
`Content-Range: bytes start-end/total`, `Content-Type: application/octet-stream` and no
|
|
1788
|
+
Authorization. Every intermediate 200 must report exactly the next expected range; the final
|
|
1789
|
+
range must return 201, whose `Location` yields `attachmentId` when parseable. Session URLs outside
|
|
1790
|
+
the allowlist fail `network_policy_rejected` without being contacted; after any later failure or
|
|
1791
|
+
interruption the helper sends one best-effort `DELETE` to cancel the session. Result:
|
|
1792
|
+
`{ attachmentId?, name, size }` where `size` is the uploaded byte count. A created attachment
|
|
1793
|
+
whose ID is missing still succeeds without `attachmentId`. Failures are code/status-only
|
|
1794
|
+
`ConnectorFileTransferError`s and never include the session URL, token or provider bodies; the
|
|
1795
|
+
draft is never sent, but a failure after dispatch may still have attached the file, so list
|
|
1796
|
+
attachments before retrying. Graph documents a known issue for large attachments in shared or
|
|
1797
|
+
delegated mailboxes.
|
|
1798
|
+
- R2's separate `R2ObjectClient` host port supports binding or signed transport, not an AWS dependency.
|
|
1799
|
+
Get takes `{ bucket, key, expectedEtag? }`; create takes `{ bucket, key, bytes }`; update requires
|
|
1800
|
+
`expectedEtag`. Hosts atomically implement `condition: { kind: 'absent' }` as `If-None-Match: *`,
|
|
1801
|
+
or `{ kind: 'etag', etag }` as concrete `If-Match`; never HEAD-then-PUT or weaken conditions.
|
|
1802
|
+
Preserve HTTP ETag quoting; translate explicitly for bindings. Missing GET fails `not_found`,
|
|
1803
|
+
conditional GET without body/conditional PUT returning null fails `conflict`, not empty success.
|
|
1804
|
+
Host owns credentials, authorized integration/bucket/key selection, signing and bounded I/O.
|
|
1805
|
+
ETags cannot distinguish all identical-content rewrites. Cap: **100,000,000 bytes**.
|
|
1806
|
+
`R2Presigner`/`r2_storage.upload_url` stay unchanged and do not inherit these conditions.
|
|
1807
|
+
|
|
1808
|
+
Dropbox, OneDrive and R2 are single-request bounded uploads only: larger files fail
|
|
1809
|
+
`upload_session_required` before transport; smaller host budgets fail `response_too_large`. Only
|
|
1810
|
+
Outlook draft attachments use upload sessions; there is no resume, and no claim of conditional R2
|
|
1811
|
+
multipart completion. No automatic write retry. A timeout,
|
|
1812
|
+
cancellation or malformed success response may follow a committed write; hosts reconcile provider
|
|
1813
|
+
state rather than dropping conditions or silently changing modes.
|
|
1814
|
+
|
|
1815
|
+
### Retrieval contracts
|
|
1816
|
+
|
|
1817
|
+
- Drive blob input: `{ fileId, resourceKey? }`; export additionally needs `mimeType`. Metadata checks
|
|
1818
|
+
caller-specific `capabilities.canDownload`, not role flags in isolation. Shared drives and resource
|
|
1819
|
+
keys are supported; no abuse acknowledgement, shortcut chasing or Vids long-running download.
|
|
1820
|
+
Default consent is `drive.file`; trusted budget `contentAccess: 'readonly'` selects the opt-in
|
|
1821
|
+
`GoogleDriveReadonlyOAuthCredentialSlot` (`drive.readonly`, restricted broad consent).
|
|
1822
|
+
Metadata-only consent is insufficient. Compatible native exports cap at **10,000,000 bytes**:
|
|
1823
|
+
Docs PDF/DOCX/ODT/RTF/text/HTML/ZIP/EPUB/Markdown; Sheets XLSX/ODS/PDF/CSV/TSV/ZIP;
|
|
1824
|
+
Slides PPTX/ODP/PDF/text; Drawings PDF/JPEG/PNG/SVG; Apps Script JSON. CSV/TSV is first-sheet only.
|
|
1825
|
+
- Fortnox preview `{ documentNumber }` uses `/preview`, not `/print`, and does not mark Sent true.
|
|
1826
|
+
It is a generated PDF, not an immutable original. The preview request sends no `Accept` header;
|
|
1827
|
+
success is verified by `%PDF-` magic bytes, not the response content type. Archive `{ fileId }` uses `/3/archive/{id}`.
|
|
1828
|
+
New `fortnox.list_supplier_invoice_files` takes `{ givenNumber, page?, limit? }`, filters internal
|
|
1829
|
+
GivenNumber, and returns `{ files, pagination }`. `FortnoxConnectFileOAuthCredentialSlot` requests
|
|
1830
|
+
`connectfile`; `FortnoxArchiveOAuthCredentialSlot` requests `archive`; preview uses `invoice`.
|
|
1831
|
+
These scopes grant provider **read and write** and are not added to the existing combined slot.
|
|
1832
|
+
Provider archive/list OpenAPI modeling is imperfect; validate sanitized responses before production.
|
|
1833
|
+
- Fortnox offer preview (`downloadFortnoxOfferPreview`) uses `/offers/{DocumentNumber}/preview` with
|
|
1834
|
+
the `offer` slot. Inbox download (`downloadFortnoxInboxFile`, `/inbox/{Id}`) refuses `root` and
|
|
1835
|
+
static folder ids, which answer folder JSON. Inbox upload (`uploadFortnoxInboxFile`) is one
|
|
1836
|
+
never-retried multipart POST through `ConnectorBinaryWriteHttpClient`, capped at
|
|
1837
|
+
`fortnoxInboxUploadMaxBytes` (50 MiB, not a documented Fortnox limit), and verifies the returned
|
|
1838
|
+
`Size`. Both inbox helpers use the `inbox` slot.
|
|
1839
|
+
- Notion accepts hosted/external provider file objects from page/property/block reads. Fourth argument
|
|
1840
|
+
`NotionFileDownloadPolicy` requires `allowHostedUrl`; external files additionally require
|
|
1841
|
+
`allowExternalUrl`. Never forward Notion credentials. Refresh expired grants by rereading the owning
|
|
1842
|
+
object; `file_upload.id` is not a download URL. No arbitrary authenticated URL-fetch API is added.
|
|
1843
|
+
- Gmail `{ messageId, attachmentId }` decodes base64url internally, validates decoded size
|
|
1844
|
+
and budgets (including JSON expansion). Inline parts without attachment IDs are not modeled.
|
|
1845
|
+
Outlook adds optional `mailbox`, checks the file discriminator and uses raw `/$value`; item/reference
|
|
1846
|
+
attachments fail. Existing shared/application-mailbox and immutable-ID guards remain. Graph's
|
|
1847
|
+
metadata size is not treated as exact raw-byte length.
|
|
1848
|
+
- IMAP/POP3 use `{ messageId, attachmentId, folder? }` through optional `EmailClient.getAttachmentBytes`.
|
|
1849
|
+
Hosts return raw decoded MIME bytes, matching IDs/byteLength and optional filename/contentType.
|
|
1850
|
+
Preserve IMAP flags, bound/release MIME streams; POP3 rejects folders and may fetch the whole message.
|
|
1851
|
+
- Telegram `{ fileId }` uses hosted `getFile` and validated `api.telegram.org/file/botTOKEN/path`.
|
|
1852
|
+
Cap **20,000,000 bytes**; no local Bot API filesystem paths or `getUpdates` calls. Token-bearing
|
|
1853
|
+
URLs never leave the host. Do not infer filename/MIME from path. Reissue getFile after grant expiry.
|
|
1854
|
+
- Todoist `todoist.list_comments` takes exactly one taskId/projectId and cursor/limit, returning
|
|
1855
|
+
metadata-only comments (Chunk) and nextCursor. Download `{ commentId }` rereads bounded metadata.
|
|
1856
|
+
Only initial `files.todoist.com` receives bearer auth; `todoist.b-cdn.net` and
|
|
1857
|
+
`d1ysz50cxb9zwl.cloudfront.net` are unauthenticated. At most five safe HTTPS redirects, no reauth.
|
|
1858
|
+
|
|
1859
|
+
### MCP reuse and host enforcement
|
|
1860
|
+
|
|
1861
|
+
Afloat's canonical `https://useafloat.com/mcp` exposes invoice/quote PDF and
|
|
1862
|
+
receipt/logo/tax-return download grants (one hour), plus receipt/logo upload-intent completion
|
|
1863
|
+
operations (`get-invoice-pdf`, `create-receipt-upload`, ...; the published schemas are in
|
|
1864
|
+
`@yolk-sdk/connectors/afloat/conformance`, see "Afloat MCP conformance" below). Receipt completion
|
|
1865
|
+
attaches or replaces atomically; receipt upload inputs allow JPEG/PNG/WebP/GIF/PDF,
|
|
1866
|
+
1–2,147,483,647 bytes, optional SHA-256. Figma discovery confirms
|
|
1867
|
+
`download_assets`, `upload_assets` (including SVG, 10 MB/asset), `use_figma` and `create_new_file`.
|
|
1868
|
+
Use dynamic MCP contracts and structured/multipart results, not duplicated SDK wrappers. Deployed
|
|
1869
|
+
Figma node-selection parameters can differ from docs. No whole `.fig` download claim. Keep grants
|
|
1870
|
+
and bytes in bounded host pipelines; approve write-capable tools as writes, not read-only tools.
|
|
1871
|
+
Evidence is metadata-only discovery and provider documentation, not live writes.
|
|
1872
|
+
|
|
1873
|
+
Hosts enforce streamed upload/response/error limits (including decompression), independent header
|
|
1874
|
+
limits, timeouts, cancellation, TLS, public DNS/socket IP policy, no ambient credentials/cookies,
|
|
1875
|
+
no automatic redirects/retries, and no URL/header/body logging. New downloads reject redirects
|
|
1876
|
+
except the bounded Todoist flow; existing OneDrive behavior is unchanged. Syntax/post-buffer checks
|
|
1877
|
+
are defense in depth, not proof of pre-buffer bounds or network isolation. Keep bytes outside agent
|
|
1878
|
+
serialization; own authorization/consent, storage, scanning, retention, format readers and safe
|
|
1879
|
+
telemetry. No app wiring or provider snapshot consistency is supplied. Fake-port tests prove SDK
|
|
1880
|
+
orchestration only.
|
|
154
1881
|
|
|
155
1882
|
## Provider actions
|
|
156
1883
|
|
|
157
|
-
| Subpath
|
|
158
|
-
|
|
|
159
|
-
| `@yolk-sdk/connectors/
|
|
160
|
-
| `@yolk-sdk/connectors/
|
|
161
|
-
| `@yolk-sdk/connectors/
|
|
162
|
-
| `@yolk-sdk/connectors/
|
|
163
|
-
| `@yolk-sdk/connectors/
|
|
164
|
-
| `@yolk-sdk/connectors/
|
|
165
|
-
| `@yolk-sdk/connectors/
|
|
1884
|
+
| Subpath | Capabilities |
|
|
1885
|
+
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1886
|
+
| `@yolk-sdk/connectors/afloat` | `afloat.mcp_auth` |
|
|
1887
|
+
| `@yolk-sdk/connectors/dropbox` | list/continue, search/continue, metadata, create folder, move, copy, delete; host-only download plus create/update |
|
|
1888
|
+
| `@yolk-sdk/connectors/email` | list/get messages, attachments, drafts, send, and IMAP read-state/flag/trash/restore/move/labels |
|
|
1889
|
+
| `@yolk-sdk/connectors/figma` | `figma.mcp_auth` |
|
|
1890
|
+
| `@yolk-sdk/connectors/fortnox` | company info; customers, invoices, suppliers, supplier invoices/files, articles, prices, cost centers, payments (incl. bookkeep), offers (incl. convert/cancel/email), print templates, inbox, settings registers, profile; host-only preview/archive/inbox I/O |
|
|
1891
|
+
| `@yolk-sdk/connectors/github` | Issues, comments, labels, sub-issues, dependencies, issue fields, pull requests, reviews, merge, repo context |
|
|
1892
|
+
| `@yolk-sdk/connectors/google` | Gmail mail and label actions; Calendar event actions; Drive metadata, folder-create, trash, and delete actions |
|
|
1893
|
+
| `@yolk-sdk/connectors/kie` | Kie image/video generation task submit (GPT Image 2, Wan 2.7) and task status actions, `KieApiKeySlot` (`kie.api_key`) |
|
|
1894
|
+
| `@yolk-sdk/connectors/linkedin-search` | `linkedin_search.search`, `linkedin_search.profile`, `linkedin_search.email` |
|
|
1895
|
+
| `@yolk-sdk/connectors/microsoft` | Outlook mail/category and OneDrive metadata/folder/move/copy/recycle actions; host-only file and attachment I/O |
|
|
1896
|
+
| `@yolk-sdk/connectors/notion` | Notion search, page, block, database, data source, user, and comment actions |
|
|
1897
|
+
| `@yolk-sdk/connectors/r2-storage` | `r2_storage.upload_url` plus host-only `R2ObjectClient` get/create/update |
|
|
1898
|
+
| `@yolk-sdk/connectors/telegram` | `telegram.send_message`, `telegram.validate` |
|
|
1899
|
+
| `@yolk-sdk/connectors/todoist` | Todoist project, task, label, and comment actions |
|
|
166
1900
|
|
|
167
|
-
R2 presigning is host-provided through `R2Presigner`; no AWS SDK dependency is bundled.
|
|
1901
|
+
R2 presigning is host-provided through `R2Presigner`; no AWS SDK dependency is bundled. `r2_storage.upload_url` includes `publicUrl` only when integration config provides `publicUrl`.
|
|
168
1902
|
|
|
169
1903
|
## Agent adapter
|
|
170
1904
|
|
|
@@ -174,17 +1908,73 @@ import { GoogleConnector } from '@yolk-sdk/connectors/google'
|
|
|
174
1908
|
|
|
175
1909
|
const toolModule = makeConnectorToolModule(GoogleConnector, {
|
|
176
1910
|
integration,
|
|
177
|
-
layer: HostConnectorLayer
|
|
178
|
-
access: action => action.includes('create') ? 'write' : 'read'
|
|
1911
|
+
layer: HostConnectorLayer
|
|
179
1912
|
})
|
|
180
1913
|
```
|
|
181
1914
|
|
|
182
1915
|
`HostConnectorLayer` should provide `CredentialResolver`, `ConnectorHttpClient`, and any other connector dependencies.
|
|
183
1916
|
|
|
1917
|
+
Connector actions can declare default `read`, `write`, or `destructive` access metadata. The agent
|
|
1918
|
+
adapter uses that declaration unless the host supplies `access`; host access resolvers always win.
|
|
1919
|
+
Google Drive folder creation and Microsoft draft/folder-create actions declare `write`. Google Drive
|
|
1920
|
+
trash/delete, Gmail `send_message`, Microsoft message sends, and OneDrive deletion declare `destructive`. OneDrive move/copy declare `write`; copy-status polling remains `read`, and hosts own approval for the initiating copy. Legacy actions without metadata default to `read`, so hosts should continue assigning explicit access
|
|
1921
|
+
when adapting other write-capable connectors. This currently includes write-capable Gmail, Google
|
|
1922
|
+
Calendar, Notion, Todoist, Telegram, and R2 actions; hosts should provide an `access` resolver for
|
|
1923
|
+
those actions rather than relying on the fallback.
|
|
1924
|
+
|
|
1925
|
+
Code mode exposure is host policy too. Pass `exposure` as one `ToolExposure` value or a resolver
|
|
1926
|
+
`(actionId, action) => ToolExposure` (`action` carries the declared `access`, or is `undefined` for
|
|
1927
|
+
an undeclared action id). Without it the tools keep the agent default (`callableBy: 'all'`).
|
|
1928
|
+
`resolveTools` still rejects invalid combinations, such as `codemode` on a tool that needs approval:
|
|
1929
|
+
|
|
1930
|
+
```ts
|
|
1931
|
+
const toolModule = makeConnectorToolModule(GoogleConnector, {
|
|
1932
|
+
integration,
|
|
1933
|
+
layer: HostConnectorLayer,
|
|
1934
|
+
exposure: (_actionId, action) =>
|
|
1935
|
+
action?.access === 'read'
|
|
1936
|
+
? { callableBy: 'codemode', discovery: 'search' }
|
|
1937
|
+
: { callableBy: 'model' }
|
|
1938
|
+
})
|
|
1939
|
+
```
|
|
1940
|
+
|
|
1941
|
+
Afloat MCP auth reads an `afloat_` API key from the host runtime credential and returns the
|
|
1942
|
+
canonical MCP endpoint and required `2026-07-28` protocol version. Keep the API key server-side;
|
|
1943
|
+
never expose the auth action through a model-callable connector module.
|
|
1944
|
+
|
|
1945
|
+
### Afloat MCP conformance (experimental)
|
|
1946
|
+
|
|
1947
|
+
`@yolk-sdk/connectors/afloat/conformance` holds no case code and never imports `@yolk-sdk/mcp`: the
|
|
1948
|
+
cases are the generic `@yolk-sdk/mcp/conformance` cases, and this subpath supplies Afloat's target
|
|
1949
|
+
and seeds. `makeAfloatMcpConformanceTarget()` runs the real `afloat.mcp_auth` over the host's
|
|
1950
|
+
`CredentialResolver` and answers the target value (`https://useafloat.com/mcp`, modern
|
|
1951
|
+
`2026-07-28`, `Authorization: Bearer <afloat_ key>`, and the public reserved invalid key
|
|
1952
|
+
`afloat_yolkconformanceinvalid0000` for the auth case). `afloatMcpConformanceLiveSeeds` name the
|
|
1953
|
+
published nine-tool subset (`afloatMcpConformanceTools`, in the provider's listing order: the
|
|
1954
|
+
source's names, titles, schemas, and annotations; the descriptions and server instructions are
|
|
1955
|
+
rewritten generically) and the two receipt-upload tools that write, and no `readTool`;
|
|
1956
|
+
`afloatMcpConformanceFixtureSeeds` add the synthetic `list-invoices` call. The eight fixtures
|
|
1957
|
+
(`afloatMcpConformanceFixtures`, every case but `mcp.legacy.session`, which does not apply to a
|
|
1958
|
+
modern server) are derived from the provider's source (owner-supplied), not a live recording: the
|
|
1959
|
+
pinned official MCP server SDK run in-process with the provider's handler options, over synthetic
|
|
1960
|
+
data, `evidence: 'unverified'`. In this repository, `pnpm conformance:mcp --target afloat` previews the run (a dry run:
|
|
1961
|
+
no network, no credential read); `--live --owner-approved --account <label>` runs the cases by hand
|
|
1962
|
+
against a practice account (a tool is called only when named with the `--read-tool` flag, never
|
|
1963
|
+
from the environment), and `@yolk-sdk/emulators/mcp` serves the fixtures as profile `afloat`.
|
|
1964
|
+
|
|
1965
|
+
Figma MCP auth reads `accessToken` plus optional `refreshToken`, `clientId`, and `clientSecret`
|
|
1966
|
+
from the runtime `OAuthCredential`. Keep these values in the host credential store.
|
|
1967
|
+
|
|
184
1968
|
## Host responsibilities
|
|
185
1969
|
|
|
186
1970
|
- Store, encrypt, refresh, revoke, and audit credentials.
|
|
187
|
-
- Own OAuth routes, callbacks, state, and
|
|
1971
|
+
- Own OAuth routes, callbacks, state, token persistence, and required-scope consent.
|
|
1972
|
+
- Provide the `ConnectorHttpClient` implementation and Effect layers required by enabled connectors.
|
|
1973
|
+
- Provide `ConnectorBinaryHttpClient` / `ConnectorBinaryWriteHttpClient` when using host-only byte APIs; never log URLs/bodies; enforce streamed limits, TLS, and connection-time DNS/IP policy.
|
|
1974
|
+
- Implement optional `ConnectorBinaryWriteHttpClient.uploadSession` only with an origin/path allowlist for pre-authenticated session URLs, no Authorization, redirects, retries, or URL logging, and response headers (including `Location`) returned intact.
|
|
1975
|
+
- Provide `R2ObjectClient` for conditional R2 get/create/update; provide `EmailClient` (including optional `getAttachmentBytes`) for email.
|
|
1976
|
+
- Keep byte results out of `makeConnectorToolModule` / generic tool JSON; own materialization, scanning, and format readers.
|
|
1977
|
+
- Preserve connector request headers and body content types while applying host networking policy.
|
|
188
1978
|
- Map integrations to users, workspaces, agents, or projects outside this package.
|
|
189
1979
|
- Authorize action execution before invoking connectors.
|
|
190
1980
|
|