@decaf-ts/integrations 0.12.0 → 0.14.0

package/lib/types/io/microsoft-excel/MicrosoftExcelService.d.cts

@@ -0,0 +1,230 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.cts";
+/**
+ * @description Configuration for the Microsoft Excel service
+ * @summary Extends {@link HttpApiServiceConfig} with the Microsoft Graph
+ * access token sent as a bearer token. When omitted, the
+ * `io.microsoftExcel` environment slice supplies the token (plus optional
+ * `baseUrl`/`timeout`).
+ * @category IO
+ * @memberOf module:integrations/io/microsoft-excel/service
+ */
+export interface MicrosoftExcelServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Microsoft Graph access token
+     * @summary Sent as `Authorization: Bearer <token>` with every API call.
+     */
+    token?: string;
+}
+/**
+ * @description Reference to an Excel workbook
+ * @summary Identifies a workbook by its drive item `itemId` and, optionally,
+ * the `driveId` that owns it. Without `driveId` the signed-in user's drive is
+ * used.
+ * @category IO
+ * @memberOf module:integrations/io/microsoft-excel/service
+ */
+export interface ExcelWorkbookRef {
+    /**
+     * @description Drive item ID of the workbook
+     */
+    itemId: string;
+    /**
+     * @description Drive ID owning the workbook (defaults to the user's drive)
+     */
+    driveId?: string;
+}
+/**
+ * @description Reference to a worksheet range
+ * @summary Carries the workbook reference plus the `worksheet` name and the
+ * A1-style `range` address (e.g. `"A1:C10"`).
+ * @category IO
+ * @memberOf module:integrations/io/microsoft-excel/service
+ */
+export interface ExcelRangeInput extends ExcelWorkbookRef {
+    /**
+     * @description Worksheet name
+     */
+    worksheet: string;
+    /**
+     * @description A1-style range address
+     */
+    range: string;
+}
+/**
+ * @description Input for writing values to a worksheet range
+ * @summary Carries the range reference plus the two-dimensional `values`
+ * matrix written to it.
+ * @category IO
+ * @memberOf module:integrations/io/microsoft-excel/service
+ */
+export interface ExcelRangeWriteInput extends ExcelRangeInput {
+    /**
+     * @description Row-major matrix of values to write
+     */
+    values: unknown[][];
+}
+/**
+ * @description Input for appending a row to an Excel table
+ * @summary Carries the workbook reference, the `tableId`, and the row
+ * `values` in table-column order.
+ * @category IO
+ * @memberOf module:integrations/io/microsoft-excel/service
+ */
+export interface ExcelTableRowInput extends ExcelWorkbookRef {
+    /**
+     * @description Table ID within the workbook
+     */
+    tableId: string;
+    /**
+     * @description Row values in table-column order
+     */
+    values: unknown[];
+}
+/**
+ * @description Microsoft Excel (Graph) workbook integration service
+ * @summary An undecorated HTTP service for listing worksheets and tables,
+ * reading and writing ranges, and appending table rows. Every operation
+ * requires a Graph access token and a workbook `itemId`; missing credentials or
+ * identifiers raise `InternalError`, and transport failures are mapped to decaf
+ * errors via {@link httpError}.
+ * @class MicrosoftExcelService
+ * @extends HttpApiService
+ * @category IO
+ * @example
+ * ```ts
+ * import { MicrosoftExcelService } from "@decaf-ts/integrations/io/microsoft-excel";
+ *
+ * const excel = new MicrosoftExcelService();
+ * await excel.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_MICROSOFT_EXCEL_TOKEN,
+ * });
+ * const range = await excel.getRange({
+ *   itemId: process.env.EXCEL_ITEM_ID ?? "",
+ *   worksheet: "Sheet1",
+ *   range: "A1:C10",
+ * });
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as MicrosoftExcelService
+ *   participant Graph as Microsoft Graph
+ *   Caller->>Service: updateRange(input)
+ *   activate Service
+ *   Service->>Service: requireAccessToken()
+ *   Service->>Graph: PATCH /me/drive/items/{id}/workbook/worksheets/{name}/range(...)
+ *   activate Graph
+ *   Graph-->>Service: updated range payload
+ *   deactivate Graph
+ *   Service-->>Caller: updated range payload
+ *   deactivate Service
+ * @memberOf module:integrations/io/microsoft-excel/service
+ */
+export declare class MicrosoftExcelService extends HttpApiService<MicrosoftExcelServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Microsoft Excel";
+    /**
+     * @description The Microsoft Graph base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://graph.microsoft.com/v1.0"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Microsoft Graph bearer authorization headers
+     * @summary Returns `Authorization: Bearer <token>` when configured, and no
+     * headers otherwise.
+     * @param {MicrosoftExcelServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    protected authHeaders(config: MicrosoftExcelServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Excel credentials and defaults from the environment
+     * @summary Reads the `io.microsoftExcel` slice and returns a partial config
+     * when an access token is configured, `undefined` otherwise. Values pass
+     * through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<MicrosoftExcelServiceConfig> | undefined} A partial config, or `undefined` when no Excel token is configured.
+     */
+    protected configFromEnvironment(): Partial<MicrosoftExcelServiceConfig> | undefined;
+    /**
+     * @description Asserts that a Microsoft Graph access token is configured
+     * @summary Delegates to the shared `requireToken()` guard used by every
+     * operation.
+     * @returns {void}
+     * @throws {InternalError} When the resolved config has no `token`.
+     */
+    protected requireAccessToken(): void;
+    /**
+     * @description Builds the Graph workbook path for a drive item
+     * @summary Uses `/drives/<driveId>/items/<itemId>/workbook` when a `driveId`
+     * is set, otherwise the signed-in user's `/me/drive/...` path.
+     * @param {ExcelWorkbookRef} input - The workbook reference.
+     * @returns {string} The workbook API path.
+     * @throws {InternalError} When `itemId` is empty.
+     */
+    private workbookPath;
+    /**
+     * @description Builds the Graph worksheet range path
+     * @summary Appends the encoded worksheet and A1 `range(address=...)`
+     * segments to the workbook path.
+     * @param {ExcelRangeInput} input - The workbook, worksheet, and range.
+     * @returns {string} The worksheet range API path.
+     * @throws {InternalError} When the worksheet or range is empty.
+     */
+    private rangePath;
+    /**
+     * @description Lists the worksheets in a workbook
+     * @summary `GET`s the workbook's `/worksheets` collection.
+     * @param {ExcelWorkbookRef} input - The workbook reference.
+     * @returns {Promise<unknown>} The Graph worksheet collection.
+     * @throws {InternalError} When no token is configured or `itemId` is empty.
+     * @throws {NotFoundError} When the workbook does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    listWorksheets(input: ExcelWorkbookRef): Promise<unknown>;
+    /**
+     * @description Reads values from a worksheet range
+     * @summary `GET`s the addressed range and returns its values and formatting
+     * payload.
+     * @param {ExcelRangeInput} input - The workbook, worksheet, and range.
+     * @returns {Promise<unknown>} The range payload.
+     * @throws {InternalError} When no token is configured, or the workbook, worksheet, or range is empty.
+     * @throws {NotFoundError} When the workbook or range does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    getRange(input: ExcelRangeInput): Promise<unknown>;
+    /**
+     * @description Writes values into a worksheet range
+     * @summary `PATCH`es the addressed range with the supplied `values` matrix
+     * and returns the updated range payload.
+     * @param {ExcelRangeWriteInput} input - The range reference and values to write.
+     * @returns {Promise<unknown>} The updated range payload.
+     * @throws {InternalError} When no token is configured, or the workbook, worksheet, or range is empty.
+     * @throws {NotFoundError} When the workbook or range does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    updateRange(input: ExcelRangeWriteInput): Promise<unknown>;
+    /**
+     * @description Lists the tables in a workbook
+     * @summary `GET`s the workbook's `/tables` collection.
+     * @param {ExcelWorkbookRef} input - The workbook reference.
+     * @returns {Promise<unknown>} The Graph table collection.
+     * @throws {InternalError} When no token is configured or `itemId` is empty.
+     * @throws {NotFoundError} When the workbook does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    listTables(input: ExcelWorkbookRef): Promise<unknown>;
+    /**
+     * @description Appends a row to an Excel table
+     * @summary `POST`s the single row to the table's `/rows/add` endpoint and
+     * returns the Graph row payload.
+     * @param {ExcelTableRowInput} input - The workbook, table, and row values.
+     * @returns {Promise<unknown>} The created table row payload.
+     * @throws {InternalError} When no token is configured, or the workbook, table, or values are missing.
+     * @throws {NotFoundError} When the workbook or table does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    addTableRow(input: ExcelTableRowInput): Promise<unknown>;
+}

package/lib/types/io/microsoft-excel/MicrosoftExcelService.d.mts

@@ -0,0 +1,230 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.mts";
+/**
+ * @description Configuration for the Microsoft Excel service
+ * @summary Extends {@link HttpApiServiceConfig} with the Microsoft Graph
+ * access token sent as a bearer token. When omitted, the
+ * `io.microsoftExcel` environment slice supplies the token (plus optional
+ * `baseUrl`/`timeout`).
+ * @category IO
+ * @memberOf module:integrations/io/microsoft-excel/service
+ */
+export interface MicrosoftExcelServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Microsoft Graph access token
+     * @summary Sent as `Authorization: Bearer <token>` with every API call.
+     */
+    token?: string;
+}
+/**
+ * @description Reference to an Excel workbook
+ * @summary Identifies a workbook by its drive item `itemId` and, optionally,
+ * the `driveId` that owns it. Without `driveId` the signed-in user's drive is
+ * used.
+ * @category IO
+ * @memberOf module:integrations/io/microsoft-excel/service
+ */
+export interface ExcelWorkbookRef {
+    /**
+     * @description Drive item ID of the workbook
+     */
+    itemId: string;
+    /**
+     * @description Drive ID owning the workbook (defaults to the user's drive)
+     */
+    driveId?: string;
+}
+/**
+ * @description Reference to a worksheet range
+ * @summary Carries the workbook reference plus the `worksheet` name and the
+ * A1-style `range` address (e.g. `"A1:C10"`).
+ * @category IO
+ * @memberOf module:integrations/io/microsoft-excel/service
+ */
+export interface ExcelRangeInput extends ExcelWorkbookRef {
+    /**
+     * @description Worksheet name
+     */
+    worksheet: string;
+    /**
+     * @description A1-style range address
+     */
+    range: string;
+}
+/**
+ * @description Input for writing values to a worksheet range
+ * @summary Carries the range reference plus the two-dimensional `values`
+ * matrix written to it.
+ * @category IO
+ * @memberOf module:integrations/io/microsoft-excel/service
+ */
+export interface ExcelRangeWriteInput extends ExcelRangeInput {
+    /**
+     * @description Row-major matrix of values to write
+     */
+    values: unknown[][];
+}
+/**
+ * @description Input for appending a row to an Excel table
+ * @summary Carries the workbook reference, the `tableId`, and the row
+ * `values` in table-column order.
+ * @category IO
+ * @memberOf module:integrations/io/microsoft-excel/service
+ */
+export interface ExcelTableRowInput extends ExcelWorkbookRef {
+    /**
+     * @description Table ID within the workbook
+     */
+    tableId: string;
+    /**
+     * @description Row values in table-column order
+     */
+    values: unknown[];
+}
+/**
+ * @description Microsoft Excel (Graph) workbook integration service
+ * @summary An undecorated HTTP service for listing worksheets and tables,
+ * reading and writing ranges, and appending table rows. Every operation
+ * requires a Graph access token and a workbook `itemId`; missing credentials or
+ * identifiers raise `InternalError`, and transport failures are mapped to decaf
+ * errors via {@link httpError}.
+ * @class MicrosoftExcelService
+ * @extends HttpApiService
+ * @category IO
+ * @example
+ * ```ts
+ * import { MicrosoftExcelService } from "@decaf-ts/integrations/io/microsoft-excel";
+ *
+ * const excel = new MicrosoftExcelService();
+ * await excel.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_MICROSOFT_EXCEL_TOKEN,
+ * });
+ * const range = await excel.getRange({
+ *   itemId: process.env.EXCEL_ITEM_ID ?? "",
+ *   worksheet: "Sheet1",
+ *   range: "A1:C10",
+ * });
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as MicrosoftExcelService
+ *   participant Graph as Microsoft Graph
+ *   Caller->>Service: updateRange(input)
+ *   activate Service
+ *   Service->>Service: requireAccessToken()
+ *   Service->>Graph: PATCH /me/drive/items/{id}/workbook/worksheets/{name}/range(...)
+ *   activate Graph
+ *   Graph-->>Service: updated range payload
+ *   deactivate Graph
+ *   Service-->>Caller: updated range payload
+ *   deactivate Service
+ * @memberOf module:integrations/io/microsoft-excel/service
+ */
+export declare class MicrosoftExcelService extends HttpApiService<MicrosoftExcelServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Microsoft Excel";
+    /**
+     * @description The Microsoft Graph base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://graph.microsoft.com/v1.0"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Microsoft Graph bearer authorization headers
+     * @summary Returns `Authorization: Bearer <token>` when configured, and no
+     * headers otherwise.
+     * @param {MicrosoftExcelServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    protected authHeaders(config: MicrosoftExcelServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Excel credentials and defaults from the environment
+     * @summary Reads the `io.microsoftExcel` slice and returns a partial config
+     * when an access token is configured, `undefined` otherwise. Values pass
+     * through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<MicrosoftExcelServiceConfig> | undefined} A partial config, or `undefined` when no Excel token is configured.
+     */
+    protected configFromEnvironment(): Partial<MicrosoftExcelServiceConfig> | undefined;
+    /**
+     * @description Asserts that a Microsoft Graph access token is configured
+     * @summary Delegates to the shared `requireToken()` guard used by every
+     * operation.
+     * @returns {void}
+     * @throws {InternalError} When the resolved config has no `token`.
+     */
+    protected requireAccessToken(): void;
+    /**
+     * @description Builds the Graph workbook path for a drive item
+     * @summary Uses `/drives/<driveId>/items/<itemId>/workbook` when a `driveId`
+     * is set, otherwise the signed-in user's `/me/drive/...` path.
+     * @param {ExcelWorkbookRef} input - The workbook reference.
+     * @returns {string} The workbook API path.
+     * @throws {InternalError} When `itemId` is empty.
+     */
+    private workbookPath;
+    /**
+     * @description Builds the Graph worksheet range path
+     * @summary Appends the encoded worksheet and A1 `range(address=...)`
+     * segments to the workbook path.
+     * @param {ExcelRangeInput} input - The workbook, worksheet, and range.
+     * @returns {string} The worksheet range API path.
+     * @throws {InternalError} When the worksheet or range is empty.
+     */
+    private rangePath;
+    /**
+     * @description Lists the worksheets in a workbook
+     * @summary `GET`s the workbook's `/worksheets` collection.
+     * @param {ExcelWorkbookRef} input - The workbook reference.
+     * @returns {Promise<unknown>} The Graph worksheet collection.
+     * @throws {InternalError} When no token is configured or `itemId` is empty.
+     * @throws {NotFoundError} When the workbook does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    listWorksheets(input: ExcelWorkbookRef): Promise<unknown>;
+    /**
+     * @description Reads values from a worksheet range
+     * @summary `GET`s the addressed range and returns its values and formatting
+     * payload.
+     * @param {ExcelRangeInput} input - The workbook, worksheet, and range.
+     * @returns {Promise<unknown>} The range payload.
+     * @throws {InternalError} When no token is configured, or the workbook, worksheet, or range is empty.
+     * @throws {NotFoundError} When the workbook or range does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    getRange(input: ExcelRangeInput): Promise<unknown>;
+    /**
+     * @description Writes values into a worksheet range
+     * @summary `PATCH`es the addressed range with the supplied `values` matrix
+     * and returns the updated range payload.
+     * @param {ExcelRangeWriteInput} input - The range reference and values to write.
+     * @returns {Promise<unknown>} The updated range payload.
+     * @throws {InternalError} When no token is configured, or the workbook, worksheet, or range is empty.
+     * @throws {NotFoundError} When the workbook or range does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    updateRange(input: ExcelRangeWriteInput): Promise<unknown>;
+    /**
+     * @description Lists the tables in a workbook
+     * @summary `GET`s the workbook's `/tables` collection.
+     * @param {ExcelWorkbookRef} input - The workbook reference.
+     * @returns {Promise<unknown>} The Graph table collection.
+     * @throws {InternalError} When no token is configured or `itemId` is empty.
+     * @throws {NotFoundError} When the workbook does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    listTables(input: ExcelWorkbookRef): Promise<unknown>;
+    /**
+     * @description Appends a row to an Excel table
+     * @summary `POST`s the single row to the table's `/rows/add` endpoint and
+     * returns the Graph row payload.
+     * @param {ExcelTableRowInput} input - The workbook, table, and row values.
+     * @returns {Promise<unknown>} The created table row payload.
+     * @throws {InternalError} When no token is configured, or the workbook, table, or values are missing.
+     * @throws {NotFoundError} When the workbook or table does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    addTableRow(input: ExcelTableRowInput): Promise<unknown>;
+}

package/lib/types/io/microsoft-excel/index.d.cts

@@ -0,0 +1 @@
+export * from "./MicrosoftExcelService.d.cts";

package/lib/types/io/microsoft-excel/index.d.mts

@@ -0,0 +1 @@
+export * from "./MicrosoftExcelService.d.mts";

package/lib/types/io/microsoft-sharepoint/MicrosoftSharePointService.d.cts

@@ -0,0 +1,226 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.cts";
+/**
+ * @description Configuration for the Microsoft SharePoint service
+ * @summary Extends {@link HttpApiServiceConfig} with the Microsoft Graph
+ * access token sent as a bearer token. When omitted, the
+ * `io.microsoftSharePoint` environment slice supplies the token (plus optional
+ * `baseUrl`/`timeout`).
+ * @category IO
+ * @memberOf module:integrations/io/microsoft-sharepoint/service
+ */
+export interface MicrosoftSharePointServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Microsoft Graph access token
+     * @summary Sent as `Authorization: Bearer <token>` with every API call.
+     */
+    token?: string;
+}
+/**
+ * @description Input for listing SharePoint list items
+ * @summary Carries the owning `siteId`, the `listId`, and optional `top` and
+ * `filter` query options.
+ * @category IO
+ * @memberOf module:integrations/io/microsoft-sharepoint/service
+ */
+export interface SharePointItemsInput {
+    /**
+     * @description SharePoint site ID
+     */
+    siteId: string;
+    /**
+     * @description List ID within the site
+     */
+    listId: string;
+    /**
+     * @description Maximum number of items to return (`$top`)
+     */
+    top?: number;
+    /**
+     * @description OData filter expression (`$filter`)
+     */
+    filter?: string;
+}
+/**
+ * @description Input for creating a SharePoint list item
+ * @summary Carries the owning `siteId`, the `listId`, and the item `fields`
+ * map to write.
+ * @category IO
+ * @memberOf module:integrations/io/microsoft-sharepoint/service
+ */
+export interface SharePointListItemInput {
+    /**
+     * @description SharePoint site ID
+     */
+    siteId: string;
+    /**
+     * @description List ID within the site
+     */
+    listId: string;
+    /**
+     * @description Column values for the new item
+     */
+    fields: Record<string, unknown>;
+}
+/**
+ * @description Input for listing a SharePoint drive folder's children
+ * @summary Carries the `siteId`, an optional folder `itemId` (default `root`),
+ * and an optional `top` cap.
+ * @category IO
+ * @memberOf module:integrations/io/microsoft-sharepoint/service
+ */
+export interface SharePointDriveItemsInput {
+    /**
+     * @description SharePoint site ID
+     */
+    siteId: string;
+    /**
+     * @description Drive item (folder) ID; defaults to the drive root
+     */
+    itemId?: string;
+    /**
+     * @description Maximum number of children to return (`$top`)
+     */
+    top?: number;
+}
+/**
+ * @description Microsoft SharePoint (Graph) integration service
+ * @summary An undecorated HTTP service for searching sites, reading a site's
+ * lists and list items, creating list items, and listing drive folder
+ * contents. Every operation requires a Graph access token; missing credentials
+ * or identifiers raise `InternalError`, and transport failures are mapped to
+ * decaf errors via {@link httpError}.
+ * @class MicrosoftSharePointService
+ * @extends HttpApiService
+ * @category IO
+ * @example
+ * ```ts
+ * import { MicrosoftSharePointService } from "@decaf-ts/integrations/io/microsoft-sharepoint";
+ *
+ * const sharepoint = new MicrosoftSharePointService();
+ * await sharepoint.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_MICROSOFT_SHAREPOINT_TOKEN,
+ * });
+ * const sites = await sharepoint.listSites("ops");
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as MicrosoftSharePointService
+ *   participant Graph as Microsoft Graph
+ *   Caller->>Service: listItems(input)
+ *   activate Service
+ *   Service->>Service: requireAccessToken()
+ *   Service->>Graph: GET /sites/{siteId}/lists/{listId}/items
+ *   activate Graph
+ *   Graph-->>Service: list items payload
+ *   deactivate Graph
+ *   Service-->>Caller: list items payload
+ *   deactivate Service
+ * @memberOf module:integrations/io/microsoft-sharepoint/service
+ */
+export declare class MicrosoftSharePointService extends HttpApiService<MicrosoftSharePointServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Microsoft SharePoint";
+    /**
+     * @description The Microsoft Graph base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://graph.microsoft.com/v1.0"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Microsoft Graph bearer authorization headers
+     * @summary Returns `Authorization: Bearer <token>` when configured, and no
+     * headers otherwise.
+     * @param {MicrosoftSharePointServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    protected authHeaders(config: MicrosoftSharePointServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the SharePoint credentials and defaults from the environment
+     * @summary Reads the `io.microsoftSharePoint` slice and returns a partial
+     * config when an access token is configured, `undefined` otherwise. Values
+     * pass through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<MicrosoftSharePointServiceConfig> | undefined} A partial config, or `undefined` when no SharePoint token is configured.
+     */
+    protected configFromEnvironment(): Partial<MicrosoftSharePointServiceConfig> | undefined;
+    /**
+     * @description Asserts that a Microsoft Graph access token is configured
+     * @summary Delegates to the shared `requireToken()` guard used by every
+     * operation.
+     * @returns {void}
+     * @throws {InternalError} When the resolved config has no `token`.
+     */
+    protected requireAccessToken(): void;
+    /**
+     * @description Builds the encoded path for a SharePoint site
+     * @summary Validates the site ID and URL-encodes it into `/sites/<id>`.
+     * @param {string} siteId - The SharePoint site ID.
+     * @returns {string} The site API path.
+     * @throws {InternalError} When `siteId` is empty.
+     */
+    private sitePath;
+    /**
+     * @description Searches SharePoint sites
+     * @summary `GET`s `/sites` with a `search` term (default `"*"`).
+     * @param {string} [search] - Site search term; defaults to `"*"`.
+     * @returns {Promise<unknown>} The site collection payload.
+     * @throws {InternalError} When no token is configured.
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    listSites(search?: string): Promise<unknown>;
+    /**
+     * @description Fetches a SharePoint site
+     * @summary `GET`s `/sites/<id>` and returns the site payload.
+     * @param {string} siteId - The site ID to fetch.
+     * @returns {Promise<unknown>} The site payload.
+     * @throws {InternalError} When no token is configured or the site ID is empty.
+     * @throws {NotFoundError} When the site does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    getSite(siteId: string): Promise<unknown>;
+    /**
+     * @description Lists the lists in a SharePoint site
+     * @summary `GET`s `/sites/<id>/lists`.
+     * @param {string} siteId - The site whose lists are listed.
+     * @returns {Promise<unknown>} The list collection payload.
+     * @throws {InternalError} When no token is configured or the site ID is empty.
+     * @throws {NotFoundError} When the site does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    listLists(siteId: string): Promise<unknown>;
+    /**
+     * @description Lists items in a SharePoint list
+     * @summary `GET`s the list's `/items` endpoint expanding `fields` and
+     * applying the optional `$top` and `$filter` options.
+     * @param {SharePointItemsInput} input - The site, list, and query options.
+     * @returns {Promise<unknown>} The list item collection payload.
+     * @throws {InternalError} When no token is configured, or the site or list ID is empty.
+     * @throws {NotFoundError} When the site or list does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the query.
+     */
+    listItems(input: SharePointItemsInput): Promise<unknown>;
+    /**
+     * @description Creates a SharePoint list item
+     * @summary `POST`s the `fields` map to the list's `/items` endpoint.
+     * @param {SharePointListItemInput} input - The site, list, and item fields.
+     * @returns {Promise<unknown>} The created item payload.
+     * @throws {InternalError} When no token is configured, or the site, list, or fields are missing.
+     * @throws {NotFoundError} When the site or list does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the item.
+     */
+    createListItem(input: SharePointListItemInput): Promise<unknown>;
+    /**
+     * @description Lists the children of a SharePoint drive folder
+     * @summary `GET`s `/sites/<id>/drive/items/<item or root>/children` with an
+     * optional `$top` cap.
+     * @param {SharePointDriveItemsInput} input - The site, folder, and result cap.
+     * @returns {Promise<unknown>} The drive item collection payload.
+     * @throws {InternalError} When no token is configured or the site ID is empty.
+     * @throws {NotFoundError} When the site or folder does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    listDriveItems(input: SharePointDriveItemsInput): Promise<unknown>;
+}