@harborclient/sdk 1.0.40 → 1.0.41

package/dist/snippets.d.ts

@@ -27,9 +27,9 @@ interface HcHeaderApi {
 }
 
 /**
- * Variable helpers on hc.variables, hc.collection.variables, hc.environment.variables, and hc.globals.
+ * Variable bag helpers shared by hc.collection.variables, hc.environment.variables, and hc.globals.
  */
-interface HcVariablesApi {
+interface HcVariableBagApi {
   /**
    * Returns a variable value, preferring values set in the current script run.
    */
@@ -40,12 +40,183 @@ interface HcVariablesApi {
    */
   set(key: string, value: unknown): void;
 
+  /**
+   * Removes a single key from this scope for the remainder of the script run.
+   */
+  clear(key: string): void;
+}
+
+/**
+ * Request-scoped variable helpers on hc.request.variables.
+ */
+interface HcRequestVariablesApi extends HcVariableBagApi {
   /**
    * Replaces {{variable}} tokens and dynamic $ tokens in a template string.
    */
   replaceIn(template: unknown): string;
 }
 
+/**
+ * Auth type selector for hc.request.auth and hc.collection.auth.
+ */
+type HcAuthType = 'none' | 'basic' | 'bearer' | 'oauth2';
+
+/**
+ * OAuth client credential transport for hc.*.auth when type is oauth2.
+ */
+type HcOAuth2ClientAuth = 'header' | 'body';
+
+/**
+ * Flat auth field names accepted by hc.*.auth.update().
+ */
+type HcAuthField =
+  | 'type'
+  | 'token'
+  | 'username'
+  | 'password'
+  | 'tokenUrl'
+  | 'clientId'
+  | 'clientSecret'
+  | 'scope'
+  | 'audience'
+  | 'clientAuth';
+
+/**
+ * Partial flat auth object accepted by hc.request.auth.set() and hc.collection.auth.set().
+ *
+ * Merges onto the current auth configuration; switching type preserves stored
+ * credentials for other types.
+ */
+interface HcAuthInput {
+  type?: HcAuthType;
+  token?: string;
+  username?: string;
+  password?: string;
+  tokenUrl?: string;
+  clientId?: string;
+  clientSecret?: string;
+  scope?: string;
+  audience?: string;
+  clientAuth?: HcOAuth2ClientAuth;
+}
+
+/**
+ * Flat auth shape returned by hc.request.auth.get() and hc.collection.auth.get().
+ *
+ * Includes only fields relevant to the active auth type.
+ */
+type HcAuthSnapshot =
+  | { type: 'none' }
+  | { type: 'basic'; username: string; password: string }
+  | { type: 'bearer'; token: string }
+  | {
+      type: 'oauth2';
+      tokenUrl: string;
+      clientId: string;
+      clientSecret: string;
+      scope: string;
+      audience: string;
+      clientAuth: HcOAuth2ClientAuth;
+    };
+
+/**
+ * Auth helpers on hc.request.auth and hc.collection.auth.
+ *
+ * Request auth changes apply to the current send only. Collection auth changes
+ * persist to the collection when the send completes.
+ */
+interface HcAuthApi {
+  /**
+   * Returns the active auth fields as a flat object for the current auth type.
+   */
+  get(): HcAuthSnapshot;
+
+  /**
+   * Merges auth configuration from a partial flat auth object.
+   */
+  set(input: HcAuthInput): void;
+
+  /**
+   * Updates a single flat auth field, such as type or token.
+   */
+  update(field: HcAuthField, value: unknown): void;
+}
+
+/**
+ * Cookie bag for the request host resolved at send start.
+ * URL changes mid-script do not retarget this bag.
+ */
+interface HcCookieApi {
+  /**
+   * Returns a cookie value by name, preferring values set in the current script run.
+   */
+  get(name: string): string | undefined;
+
+  /**
+   * Sets a cookie for the request host for the remainder of the script run.
+   */
+  set(name: string, value: unknown): void;
+
+  /**
+   * Removes a single cookie by name for the remainder of the script run.
+   */
+  clear(name: string): void;
+}
+
+/**
+ * Collection runner flow control available in pre/post scripts during a run.
+ */
+interface HcExecutionApi {
+  /**
+   * Jumps to the named request in the active collection run, or stops the run when null.
+   */
+  setNextRequest(name: string | null): void;
+
+  /**
+   * Skips the HTTP send and post-request scripts for the current request.
+   */
+  skipRequest(): void;
+}
+
+/**
+ * Postman-compatible script execution metadata (pm.info equivalent).
+ */
+interface HcInfoApi {
+  /** `"prerequest"` for pre-request scripts, `"test"` for post-request scripts. */
+  readonly eventName: 'prerequest' | 'test';
+  /** Display name of the saved request. */
+  readonly requestName: string;
+  /** Saved request database id as a string, or empty when unsaved. */
+  readonly requestId: string;
+  /** Collection run iteration index; 0 for manual sends and non-data-driven runs. */
+  readonly iteration: number;
+}
+
+/**
+ * Outbound request payload accepted by hc.sendRequest.
+ */
+interface HcSendRequestInput {
+  method?: string;
+  url: string;
+  headers?: Array<{ key: string; value: string; enabled?: boolean }> | Record<string, string>;
+  params?: Array<{ key: string; value: string; enabled?: boolean }>;
+  body?: string;
+  bodyType?: 'none' | 'json' | 'text' | 'multipart' | 'urlencoded';
+  body_type?: 'none' | 'json' | 'text' | 'multipart' | 'urlencoded';
+}
+
+/**
+ * Response snapshot returned by hc.sendRequest.
+ */
+interface HcSendRequestResponse {
+  readonly code: number;
+  readonly status: string;
+  readonly headers: Record<string, string>;
+  readonly responseTime: number;
+  text(): string;
+  json(): unknown;
+}
+
 /**
  * Chai-lite matcher returned by hc.expect(actual).
  */
@@ -99,22 +270,38 @@ interface HcScriptApi {
     url: string;
     body: string;
     headers: HcHeaderApi;
+    auth: HcAuthApi;
+    variables: HcRequestVariablesApi;
   };
-  variables: HcVariablesApi;
   collection: {
     readonly id: number | null;
     readonly name: string;
-    variables: HcVariablesApi;
+    variables: HcVariableBagApi;
     headers: HcHeaderApi;
+    auth: HcAuthApi;
   };
   environment: {
     readonly name: string;
-    variables: HcVariablesApi;
+    variables: HcVariableBagApi;
   };
-  globals: HcVariablesApi;
+  globals: HcVariableBagApi;
+  cookies: HcCookieApi;
+  execution: HcExecutionApi;
+  /** Read-only metadata about the current script run (Postman pm.info equivalent). */
+  info: HcInfoApi;
+  /**
+   * Sends an outbound HTTP request from the script sandbox.
+   * Requires Settings → General → Allow script network requests.
+   *
+   * @throws When the setting is disabled or sendRequest is unavailable in this context.
+   */
+  sendRequest(req: HcSendRequestInput): Promise<HcSendRequestResponse>;
   test(name: string, fn: () => void): void;
   expect(actual: unknown): HcExpectMatcher;
-  response: HcResponseApi;
+  /**
+   * Available in post-request scripts after the primary request completes.
+   */
+  response?: HcResponseApi;
 }
 
 /**

package/dist/types.d.ts

@@ -1726,7 +1726,7 @@ export interface PluginScriptContextInit {
      */
     response?: PluginScriptResponseInit;
     /**
-     * Merged runtime variables for hc.variables, hc.collection.variables,
+     * Merged runtime variables for hc.request.variables, hc.collection.variables,
      * hc.environment.variables, and hc.globals lookups.
      */
     variables?: Record<string, string>;
@@ -1772,7 +1772,7 @@ export interface PluginScriptRunResult {
      */
     request: PluginScriptRequestInit;
     /**
-     * Ephemeral variable sets from hc.variables.set.
+     * Ephemeral variable sets from hc.request.variables.set.
      */
     variableSets: Record<string, string>;
     /**
@@ -1836,7 +1836,7 @@ export interface PluginScriptContext {
  * Script sandbox factory available on {@link MainPluginContext.scripts}.
  *
  * Runs user scripts with the same hc object as collection and request pre/post scripts
- * (`hc.request`, `hc.variables`, `hc.collection`, `hc.environment`, `hc.globals`,
+ * (`hc.request`, `hc.collection`, `hc.environment`, `hc.globals`,
  * `hc.test`, `hc.expect`, and `hc.response` when a response is provided).
  */
 export interface PluginScripts {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harborclient/sdk",
-  "version": "1.0.40",
+  "version": "1.0.41",
   "description": "TypeScript SDK for HarborClient development.",
   "keywords": [
     "harborclient",