@zackbart/connecta 0.28.0 → 0.29.0

package/dist/providers/docs/skill.generated.js

@@ -0,0 +1,9 @@
+// Generated by scripts/generate-providers.mjs; do not edit.
+export const skill = {
+    "content": "# Google Docs usage\n\nReads and edits Google Docs as the signed-in person through Workspace delegation; it cannot search or list documents.\n\nConnection purpose: \n\n## Whose documents\n\nEvery call acts as the Workspace account deployment config maps the caller\nto, and reaches exactly the documents Drive shares with that person. No\nargument names an account. A call with none mapped fails `auth_required`;\nonly an operator can change the mapping.\n\n## Finding a document\n\nThere is no search or list tool. Take the id from a\ndocs.google.com URL (the part after `/d/`), from the person, or from a\nGoogle Drive connection's file search. A failure on an id may mean it does\nnot exist or is not shared with this person; Google does not say which.\n\n## Reading\n\n- `get_document` renders every tab as markdown-ish text: headings, lists,\n  links, tables as pipe rows, footnotes after the body, images and other\n  embeds as bracketed markers. Headers, footers, floating images, and\n  comments are not rendered; a tab's `notRendered` names any it holds, and\n  `suggestion_marks` there means the text mixes unmarked suggested\n  insertions and deletions in (read with `suggestions` to preview). Text past `maxChars` (shared across tabs) ends with a marker;\n  pass `tabId` to read one tab.\n- Before an index-based edit, read with `withIndexes: true` and target an\n  element's `startIndex`/`endIndex`. A long document's rows page with\n  `page.nextCursor`; send `maxChars: 0` on later pages, and start over if\n  `revisionId` changed between them. Indexes are UTF-16 code units and\n  shift after every edit. Keep `revisionId` and pass it as\n  `requiredRevisionId`, so an edit against a document someone else has\n  changed fails `conflict` with nothing applied; re-read and recompute. Indexes\n  from a suggestions preview (`accepted`/`rejected`) are not valid for\n  edits.\n- `raw: true` returns Google's document resource for the tabs instead of\n  the rendering — styles, headers, footers, named ranges, list and segment ids\n  that `batch_update_document` requests may need. It is large: pass\n  `tabId`, and call it directly rather than inside `execute_code`,\n  which carries at most 256 KiB per result.\n- The same holds for a `maxChars` above the default: a long rendering\n  can pass here and still be refused inside `execute_code`, even when the\n  program would only measure it. Read it with a direct `call_tool`, paged\n  with `connecta.result`, or read one tab at a time.\n\n## Editing\n\n- `create_document` makes a new document in My Drive's root. Never create\n  again after a failure that may have left one behind; the message says\n  which. When the document exists but its starting text failed, the message\n  names its id: append the text with `append_text` straight away only when\n  Google refused it; otherwise read the document first and append only what\n  is missing.\n- An edit sent with no answer back, answered with a server error, or\n  redirected says its outcome is unknown: re-read before repeating it, or\n  repeat it with the same `requiredRevisionId`, which Google refuses if the\n  first attempt landed. One Google answered 2xx whose reply was unreadable\n  says it was applied: do not repeat it.\n- `append_text` joins the last paragraph; begin with `\\n` for a new one.\n- `replace_all_text` changes every match at once; read first and make\n  `find` specific.\n- `batch_update_document` takes raw Docs API requests (`deleteContentRange`,\n  `updateTextStyle`, `insertTable`, `createParagraphBullets`, …) for what\n  the named tools cannot do. It is always destructive, and requires the\n  `requiredRevisionId` from the read it was planned against: up to 100\n  requests, each exactly one generally available kind (the Developer Preview\n  comment and suggestion kinds are refused). Several requests in one\n  call apply atomically, and each sees the index shifts of those before it;\n  order deletions from the end of the document backwards.\n",
+    "instructionsHeading": "Connection instructions",
+    "fragments": {
+        "guide_0": "# Google Docs usage\n\nReads and edits Google Docs as the signed-in person through Workspace delegation; it cannot search or list documents.\n\nConnection purpose: ",
+        "guide_1": "\n\n## Whose documents\n\nEvery call acts as the Workspace account deployment config maps the caller\nto, and reaches exactly the documents Drive shares with that person. No\nargument names an account. A call with none mapped fails `auth_required`;\nonly an operator can change the mapping.\n\n## Finding a document\n\nThere is no search or list tool. Take the id from a\ndocs.google.com URL (the part after `/d/`), from the person, or from a\nGoogle Drive connection's file search. A failure on an id may mean it does\nnot exist or is not shared with this person; Google does not say which.\n\n## Reading\n\n- `get_document` renders every tab as markdown-ish text: headings, lists,\n  links, tables as pipe rows, footnotes after the body, images and other\n  embeds as bracketed markers. Headers, footers, floating images, and\n  comments are not rendered; a tab's `notRendered` names any it holds, and\n  `suggestion_marks` there means the text mixes unmarked suggested\n  insertions and deletions in (read with `suggestions` to preview). Text past `maxChars` (shared across tabs) ends with a marker;\n  pass `tabId` to read one tab.\n- Before an index-based edit, read with `withIndexes: true` and target an\n  element's `startIndex`/`endIndex`. A long document's rows page with\n  `page.nextCursor`; send `maxChars: 0` on later pages, and start over if\n  `revisionId` changed between them. Indexes are UTF-16 code units and\n  shift after every edit. Keep `revisionId` and pass it as\n  `requiredRevisionId`, so an edit against a document someone else has\n  changed fails `conflict` with nothing applied; re-read and recompute. Indexes\n  from a suggestions preview (`accepted`/`rejected`) are not valid for\n  edits.\n- `raw: true` returns Google's document resource for the tabs instead of\n  the rendering — styles, headers, footers, named ranges, list and segment ids\n  that `batch_update_document` requests may need. It is large: pass\n  `tabId`, and call it directly rather than inside `execute_code`,\n  which carries at most 256 KiB per result.\n- The same holds for a `maxChars` above the default: a long rendering\n  can pass here and still be refused inside `execute_code`, even when the\n  program would only measure it. Read it with a direct `call_tool`, paged\n  with `connecta.result`, or read one tab at a time.\n\n## Editing\n\n- `create_document` makes a new document in My Drive's root. Never create\n  again after a failure that may have left one behind; the message says\n  which. When the document exists but its starting text failed, the message\n  names its id: append the text with `append_text` straight away only when\n  Google refused it; otherwise read the document first and append only what\n  is missing.\n- An edit sent with no answer back, answered with a server error, or\n  redirected says its outcome is unknown: re-read before repeating it, or\n  repeat it with the same `requiredRevisionId`, which Google refuses if the\n  first attempt landed. One Google answered 2xx whose reply was unreadable\n  says it was applied: do not repeat it.\n- `append_text` joins the last paragraph; begin with `\\n` for a new one.\n- `replace_all_text` changes every match at once; read first and make\n  `find` specific.\n- `batch_update_document` takes raw Docs API requests (`deleteContentRange`,\n  `updateTextStyle`, `insertTable`, `createParagraphBullets`, …) for what\n  the named tools cannot do. It is always destructive, and requires the\n  `requiredRevisionId` from the read it was planned against: up to 100\n  requests, each exactly one generally available kind (the Developer Preview\n  comment and suggestion kinds are refused). Several requests in one\n  call apply atomically, and each sees the index shifts of those before it;\n  order deletions from the end of the document backwards.\n"
+    }
+};

package/dist/providers/drive/index.d.ts

@@ -0,0 +1,53 @@
+import { type GoogleWorkspaceOptions } from "../_shared/google/workspace.js";
+export type { GoogleServiceAccount, GoogleSubjectContext, GoogleWorkspaceOptions, GoogleWorkspaceSubject, } from "../_shared/google/workspace.js";
+/**
+ * Drive's API root. Uploads use the same path beneath `/upload` on the same
+ * origin, which the provider derives from this (or from a `baseUrl` override).
+ */
+export declare const DRIVE_API_BASE_URL = "https://www.googleapis.com/drive/v3";
+/**
+ * Exactly the scope this connection requests, and exactly what the Admin
+ * console's domain-wide delegation entry must list. Full `drive`, because
+ * `drive.file` reaches only files the app itself created and every narrower
+ * scope is read-only.
+ */
+export declare const DRIVE_SCOPES: readonly ["https://www.googleapis.com/auth/drive"];
+/** Options for {@link drive}: the shared Workspace delegation options. */
+export type DriveOptions = GoogleWorkspaceOptions;
+/**
+ * A maintained Google Drive connection acting as each signed-in Workspace
+ * user through a delegated service account.
+ *
+ * Setup, once per Workspace (shared with every Workspace provider):
+ *
+ * 1. In a Google Cloud project, enable the **Google Drive API**.
+ * 2. Create a service account. Grant it no IAM roles: delegation, not project
+ *    permission, is what reaches users' files.
+ * 3. Create a JSON key for it. If key creation is refused, the organization
+ *    policy `iam.disableServiceAccountKeyCreation` is enforced; an org policy
+ *    administrator can override it for this project alone.
+ * 4. Copy the service account's numeric **client ID** (the key's `client_id`).
+ * 5. As a Workspace super admin: Admin console → Security → Access and data
+ *    control → API controls → Manage Domain Wide Delegation → Add new (or edit
+ *    the client's existing entry, adding to its scopes). Paste the client ID
+ *    and exactly this scope ({@link DRIVE_SCOPES}):
+ *    `https://www.googleapis.com/auth/drive`.
+ *    A new grant can take up to 24 hours to apply.
+ * 6. Configure inbound auth: a `subject` function is never asked about an
+ *    open deployment's anonymous requests, which fail `auth_required`.
+ *    Then give the deployment the key as a secret and map callers to accounts:
+ *
+ * ```ts
+ * drive("files", {
+ *   purpose: "Staff documents and shared drives",
+ *   serviceAccount: env.GOOGLE_SERVICE_ACCOUNT_JSON,
+ *   subject: (identity) => accounts[identity.principal?.id ?? ""],
+ * });
+ * ```
+ *
+ * The `drive` scope reaches everything the user can; the tool surface is what
+ * keeps this connection from deleting a file permanently or transferring
+ * ownership. Every write crosses host approval through call_destructive_tool
+ * or a trusted program.
+ */
+export declare const drive: import("../../provider.js").ProviderFactory<GoogleWorkspaceOptions>;