@zackbart/connecta 0.28.1 → 0.29.0

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

@@ -0,0 +1,54 @@
+import { type GoogleWorkspaceOptions } from "../_shared/google/workspace.js";
+export type { GoogleServiceAccount, GoogleSubjectContext, GoogleWorkspaceOptions, GoogleWorkspaceSubject, } from "../_shared/google/workspace.js";
+/**
+ * The Sheets API root. Every path the tools send is beneath
+ * `/spreadsheets`; the delegated token decides which ones the user can open.
+ */
+export declare const SHEETS_API_BASE_URL = "https://sheets.googleapis.com/v4";
+/**
+ * Exactly the scope this connection requests, and what the Admin console's
+ * domain-wide delegation entry must add for it. One scope reads and writes
+ * every spreadsheet the user can open; Google offers no narrower one that
+ * writes.
+ */
+export declare const SHEETS_SCOPES: readonly ["https://www.googleapis.com/auth/spreadsheets"];
+/** Options for {@link sheets}: the shared Workspace delegation options. */
+export type SheetsOptions = GoogleWorkspaceOptions;
+/**
+ * A maintained Google Sheets 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 Sheets API**.
+ * 2. Create a service account. Grant it no IAM roles: delegation, not project
+ *    permission, is what reaches spreadsheets.
+ * 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 ID's existing entry — one client ID has one entry, so add
+ *    to the scopes another Workspace provider already listed rather than
+ *    replacing them). The scope this connection needs ({@link SHEETS_SCOPES}):
+ *    `https://www.googleapis.com/auth/spreadsheets`.
+ *    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
+ * sheets("sheets", {
+ *   purpose: "Finance and attendance spreadsheets",
+ *   serviceAccount: env.GOOGLE_SERVICE_ACCOUNT_JSON,
+ *   subject: (identity) => accounts[identity.principal?.id ?? ""],
+ * });
+ * ```
+ *
+ * Reads are read-only. `create_spreadsheet`, `add_sheet`, and `append_values`
+ * are additive writes the host approves through call_destructive_tool or a
+ * trusted program; the value writes, `clear_values`, and the raw
+ * `batch_update_spreadsheet` are destructive.
+ */
+export declare const sheets: import("../../provider.js").ProviderFactory<GoogleWorkspaceOptions>;