@saptools/sharepoint-excel 0.1.1 → 0.1.3

package/README.md

@@ -11,7 +11,7 @@ Create `.xlsx` files, read workbook content, append records, update cells, and a
 [![install size](https://packagephobia.com/badge?p=@saptools/sharepoint-excel)](https://packagephobia.com/result?p=@saptools/sharepoint-excel)
 [![types](https://img.shields.io/npm/types/@saptools/sharepoint-excel.svg?style=flat&color=3178C6&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 
-[Install](#-install) • [Quick Start](#-quick-start) • [CLI](#-cli) • [Security](#-credential-security) • [API](#-programmatic-usage)
+[Install](#-install) • [Quick Start](#-quick-start) • [CLI](#-cli) • [Security](#-credential-security)
 
 </div>
 
@@ -29,24 +29,13 @@ Create `.xlsx` files, read workbook content, append records, update cells, and a
 - 🧪 **Fake-backed e2e tests**: package tests do not call real Microsoft Graph or SharePoint
 - 🧰 **CLI and typed API**: every CLI action is backed by exported TypeScript functions
 
-> [!NOTE]
-> Microsoft Graph's direct Excel workbook APIs are excellent for delegated user flows, but several workbook mutation endpoints do not support application permissions. This package intentionally treats SharePoint as file storage, edits the workbook locally, and uploads the changed `.xlsx` with conflict protection.
-
----
-
 ## 📦 Install
 
 ```bash
-# Global CLI
 npm install -g @saptools/sharepoint-excel
-
-# Or as a dependency
-npm install @saptools/sharepoint-excel
-# pnpm add @saptools/sharepoint-excel
-# yarn add @saptools/sharepoint-excel
 ```
 
-Requires **Node.js >= 20**. The CLI binary is `saptools-sharepoint-excel`.
+Requires **Node.js >= 20**. The CLI binary is `sharepoint-excel`.
 
 ---
 
@@ -54,7 +43,7 @@ Requires **Node.js >= 20**. The CLI binary is `saptools-sharepoint-excel`.
 
 ```bash
 # 1. Store an app-only SharePoint profile
-saptools-sharepoint-excel config set \
+sharepoint-excel config set \
   --tenant "11111111-1111-1111-1111-111111111111" \
   --client-id "22222222-2222-2222-2222-222222222222" \
   --client-secret "<your-client-secret>" \
@@ -62,30 +51,30 @@ saptools-sharepoint-excel config set \
   --drive "Documents"
 
 # 2. Prove auth and target resolution
-saptools-sharepoint-excel test
+sharepoint-excel test
 
 # 3. Create a workbook without overwriting an existing file
-saptools-sharepoint-excel create \
+sharepoint-excel create \
   --path "Reports/orders.xlsx" \
   --sheet "Orders" \
   --headers "Name,Amount,Status" \
   --rows '[{"Name":"Coffee","Amount":3,"Status":"open"}]'
 
 # 4. Append one object by matching row 1 headers
-saptools-sharepoint-excel append \
+sharepoint-excel append \
   --path "Reports/orders.xlsx" \
   --sheet "Orders" \
   --record '{"Name":"Tea","Amount":8,"Status":"open"}'
 
 # 5. Update one cell
-saptools-sharepoint-excel update-cell \
+sharepoint-excel update-cell \
   --path "Reports/orders.xlsx" \
   --sheet "Orders" \
   --cell "C2" \
   --value '"closed"'
 
 # 6. Read workbook JSON
-saptools-sharepoint-excel read --path "Reports/orders.xlsx" --json
+sharepoint-excel read --path "Reports/orders.xlsx" --json
 ```
 
 For CI, every command can also read credentials from environment variables:
@@ -121,7 +110,7 @@ The CLI also accepts the shorter `SHAREPOINT_TENANT_ID`, `SHAREPOINT_CLIENT_ID`,
 Store a reusable local profile.
 
 ```bash
-saptools-sharepoint-excel config set \
+sharepoint-excel config set \
   --profile finance \
   --tenant "$SHAREPOINT_EXCEL_TENANT_ID" \
   --client-id "$SHAREPOINT_EXCEL_CLIENT_ID" \
@@ -140,7 +129,7 @@ For headless CI containers where an OS keyring is unavailable, an explicit plain
 
 ```bash
 SAPTOOLS_SHAREPOINT_EXCEL_ALLOW_PLAINTEXT=1 \
-saptools-sharepoint-excel config set --store file --allow-plaintext-secret ...
+sharepoint-excel config set --store file --allow-plaintext-secret ...
 ```
 
 Use that only in controlled CI environments. The file is written with `0600` permissions under `~/.saptools/sharepoint-excel/secrets.json`.
@@ -148,8 +137,8 @@ Use that only in controlled CI environments. The file is written with `0600` per
 ### 👀 `config get`
 
 ```bash
-saptools-sharepoint-excel config get --profile finance
-saptools-sharepoint-excel config get --profile finance --json
+sharepoint-excel config get --profile finance
+sharepoint-excel config get --profile finance --json
 ```
 
 Secrets are never printed.
@@ -157,7 +146,7 @@ Secrets are never printed.
 ### 🧹 `config remove`
 
 ```bash
-saptools-sharepoint-excel config remove --profile finance
+sharepoint-excel config remove --profile finance
 ```
 
 Removes both profile metadata and the stored secret.
@@ -167,15 +156,15 @@ Removes both profile metadata and the stored secret.
 Authenticate, resolve the site, and list document libraries.
 
 ```bash
-saptools-sharepoint-excel test
-saptools-sharepoint-excel test --json
+sharepoint-excel test
+sharepoint-excel test --json
 ```
 
 ### 🗂️ `drives`
 
 ```bash
-saptools-sharepoint-excel drives
-saptools-sharepoint-excel drives --json
+sharepoint-excel drives
+sharepoint-excel drives --json
 ```
 
 Use this when you are unsure whether the document library is named `Documents`, `Shared Documents`, or something custom.
@@ -183,7 +172,7 @@ Use this when you are unsure whether the document library is named `Documents`,
 ### 🆕 `create`
 
 ```bash
-saptools-sharepoint-excel create \
+sharepoint-excel create \
   --path "Reports/orders.xlsx" \
   --sheet "Orders" \
   --headers "Name,Amount,Status" \
@@ -196,14 +185,14 @@ saptools-sharepoint-excel create \
 ### 📖 `read`
 
 ```bash
-saptools-sharepoint-excel read --path "Reports/orders.xlsx"
-saptools-sharepoint-excel read --path "Reports/orders.xlsx" --sheet "Orders" --range "A1:C10" --json
+sharepoint-excel read --path "Reports/orders.xlsx"
+sharepoint-excel read --path "Reports/orders.xlsx" --sheet "Orders" --range "A1:C10" --json
 ```
 
 ### ➕ `append`
 
 ```bash
-saptools-sharepoint-excel append \
+sharepoint-excel append \
   --path "Reports/orders.xlsx" \
   --sheet "Orders" \
   --record '{"Name":"Tea","Amount":8,"Status":"open"}'
@@ -214,7 +203,7 @@ Objects are mapped by the first row's headers by default. Use `--no-match-header
 ### 🎯 `update-cell`
 
 ```bash
-saptools-sharepoint-excel update-cell \
+sharepoint-excel update-cell \
   --path "Reports/orders.xlsx" \
   --sheet "Orders" \
   --cell "B2" \
@@ -226,7 +215,7 @@ saptools-sharepoint-excel update-cell \
 ### 📄 `add-sheet`
 
 ```bash
-saptools-sharepoint-excel add-sheet \
+sharepoint-excel add-sheet \
   --path "Reports/orders.xlsx" \
   --sheet "Audit" \
   --headers "At,Action,Actor"
@@ -250,71 +239,6 @@ Required Graph application permissions depend on your tenant model. Typical setu
 
 ---
 
-## 🧑‍💻 Programmatic Usage
-
-```ts
-import {
-  appendRemoteWorkbookRows,
-  createRemoteWorkbook,
-  openSession,
-  parseSiteRef,
-} from "@saptools/sharepoint-excel";
-
-const session = await openSession({
-  credentials: {
-    tenantId: process.env.SHAREPOINT_EXCEL_TENANT_ID ?? "",
-    clientId: process.env.SHAREPOINT_EXCEL_CLIENT_ID ?? "",
-    clientSecret: process.env.SHAREPOINT_EXCEL_CLIENT_SECRET ?? "",
-  },
-  site: parseSiteRef("contoso.sharepoint.com/sites/demo"),
-});
-
-await createRemoteWorkbook(
-  { session, driveHint: "Documents" },
-  "Reports/orders.xlsx",
-  {
-    sheetName: "Orders",
-    headers: ["Name", "Amount"],
-    rows: [{ Name: "Coffee", Amount: 3 }],
-  },
-);
-
-await appendRemoteWorkbookRows(
-  { session, driveHint: "Documents" },
-  "Reports/orders.xlsx",
-  "Orders",
-  [{ Name: "Tea", Amount: 8 }],
-  true,
-);
-```
-
-<details>
-<summary><b>📚 Main exports</b></summary>
-
-| Export | Description |
-| --- | --- |
-| `resolveRuntime()` | Resolve flags/env/profile into a SharePoint target |
-| `createProfileStore()` | Read/write redacted local profile metadata |
-| `createKeyringSecretVault()` | OS credential vault adapter |
-| `acquireAppToken()` | Request an app-only Graph token |
-| `createGraphClient()` | Minimal Graph JSON/binary client |
-| `parseSiteRef()` / `resolveSite()` | Parse and resolve SharePoint site references |
-| `listDrives()` / `selectDrive()` | Discover and select document libraries |
-| `createWorkbookBytes()` | Build a local `.xlsx` workbook |
-| `readWorkbookBytes()` | Read sheet rows from workbook bytes |
-| `appendWorkbookRows()` | Append rows in workbook bytes |
-| `updateWorkbookCell()` | Update an A1 cell in workbook bytes |
-| `addWorkbookSheet()` | Add a new worksheet |
-| `createRemoteWorkbook()` | Create SharePoint workbook without overwriting |
-| `readRemoteWorkbook()` | Download and read SharePoint workbook |
-| `appendRemoteWorkbookRows()` | Append rows and upload with ETag protection |
-| `updateRemoteWorkbookCell()` | Update one cell and upload with ETag protection |
-| `addRemoteWorkbookSheet()` | Add a worksheet and upload with ETag protection |
-
-</details>
-
----
-
 ## 🛠️ Development
 
 From the monorepo root:

package/dist/cli.js

@@ -172,7 +172,8 @@ async function redactProfile(profile, vault) {
 import { chmod as chmod2, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
 import { dirname as dirname2 } from "path";
 import { Entry } from "@napi-rs/keyring";
-var SERVICE_NAME = "saptools-sharepoint-excel";
+var SERVICE_NAME = "sharepoint-excel";
+var LEGACY_SERVICE_NAME = `saptools-${SERVICE_NAME}`;
 var SECRET_FILE_MODE = 384;
 var EMPTY_SECRET_FILE = { version: 1, entries: {} };
 function isMissingFileError2(err) {
@@ -208,11 +209,29 @@ async function writeSecretFile(path, value) {
   });
   await chmod2(path, SECRET_FILE_MODE);
 }
+function getKeyringPassword(serviceName, profileName) {
+  const password = new Entry(serviceName, profileName).getPassword();
+  return password === null || password.length === 0 ? void 0 : password;
+}
+function deleteKeyringPassword(serviceName, profileName) {
+  try {
+    new Entry(serviceName, profileName).deletePassword();
+  } catch (err) {
+    if (err instanceof Error && /not found|no entry|missing/i.test(err.message)) {
+      return;
+    }
+    throw err instanceof Error ? err : new Error(String(err));
+  }
+}
 function createKeyringSecretVault(serviceName = SERVICE_NAME) {
+  const legacyServiceName = serviceName === SERVICE_NAME ? LEGACY_SERVICE_NAME : void 0;
   return {
     getSecret(profileName) {
-      const password = new Entry(serviceName, profileName).getPassword();
-      return Promise.resolve(password === null || password.length === 0 ? void 0 : password);
+      const password = getKeyringPassword(serviceName, profileName);
+      if (password !== void 0 || legacyServiceName === void 0) {
+        return Promise.resolve(password);
+      }
+      return Promise.resolve(getKeyringPassword(legacyServiceName, profileName));
     },
     setSecret(profileName, secret) {
       new Entry(serviceName, profileName).setPassword(secret);
@@ -220,11 +239,11 @@ function createKeyringSecretVault(serviceName = SERVICE_NAME) {
     },
     deleteSecret(profileName) {
       try {
-        new Entry(serviceName, profileName).deletePassword();
-      } catch (err) {
-        if (err instanceof Error && /not found|no entry|missing/i.test(err.message)) {
-          return Promise.resolve();
+        deleteKeyringPassword(serviceName, profileName);
+        if (legacyServiceName !== void 0) {
+          deleteKeyringPassword(legacyServiceName, profileName);
         }
+      } catch (err) {
         return Promise.reject(err instanceof Error ? err : new Error(String(err)));
       }
       return Promise.resolve();
@@ -282,8 +301,11 @@ function resolveBaseUrl(options) {
   const fromEnv = (options.env ?? process2.env)[ENV_GRAPH_BASE];
   return fromEnv === void 0 || fromEnv.length === 0 ? DEFAULT_GRAPH_BASE : fromEnv.replace(/\/+$/, "");
 }
-function resolveUrl(base, path) {
+function resolveUrl(base, path, includeAuthorization) {
   if (/^https?:\/\//i.test(path)) {
+    if (includeAuthorization && new URL(path).origin !== new URL(base).origin) {
+      throw new Error("Refusing to send a Graph bearer token to a different origin");
+    }
     return path;
   }
   return `${base}${path.startsWith("/") ? path : `/${path}`}`;
@@ -318,8 +340,8 @@ async function extractErrorDetail(response) {
 }
 function buildInit(accessToken, options) {
   const headers = {
-    Authorization: `Bearer ${accessToken}`,
     Accept: "application/json",
+    ...options.includeAuthorization === false ? {} : { Authorization: `Bearer ${accessToken}` },
     ...options.headers
   };
   const init = { method: options.method ?? "GET", headers };
@@ -355,7 +377,8 @@ function createGraphClient(options) {
   const baseDelayMs = options.retry?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
   const sleepFn = options.retry?.sleepFn ?? defaultSleep;
   async function execute(path, requestOptions) {
-    const url = resolveUrl(baseUrl, path);
+    const includeAuthorization = requestOptions.includeAuthorization !== false;
+    const url = resolveUrl(baseUrl, path, includeAuthorization);
     const init = buildInit(options.accessToken, requestOptions);
     let attempt = 0;
     let response = await fetchFn(url, init);
@@ -755,6 +778,7 @@ async function uploadNewDriveFile(client, driveId, relativePath, bytes) {
   const raw = await client.requestJson(uploadUrl, {
     method: "PUT",
     rawBody: bytes,
+    includeAuthorization: false,
     headers: {
       "Content-Length": bytes.byteLength.toString(),
       "Content-Range": `bytes 0-${lastByte.toString()}/${bytes.byteLength.toString()}`,
@@ -1347,7 +1371,7 @@ function registerCommands(program) {
 // src/cli/index.ts
 async function main(argv) {
   const program = new Command();
-  program.name("saptools-sharepoint-excel").description("Create, read, and update SharePoint-hosted Excel workbooks");
+  program.name("sharepoint-excel").description("Create, read, and update SharePoint-hosted Excel workbooks");
   registerCommands(program);
   await program.parseAsync([...argv]);
 }