@harborclient/team-hub-api 0.3.4 → 0.3.6

package/dist/index.d.ts

@@ -6,5 +6,6 @@ export { toTeamHubAuth, type TeamHubAuthConfig, type TeamHubAuthType } from './a
 export { isTeamHubCollectionDeleteForbiddenError } from './isTeamHubCollectionDeleteForbiddenError.js';
 export { isTeamHubSnippetsUnsupportedError } from './isTeamHubSnippetsUnsupportedError.js';
 export { isTeamHubSnippetsForbiddenError } from './isTeamHubSnippetsForbiddenError.js';
+export { HARBOR_PROTOCOL, INVITATION_CODE_PREFIX, TEAM_HUB_JOIN_QUERY_KEYS, buildTeamHubJoinDeepLink, buildTeamHubJoinUrl, isInvitationCodeFormat, isTeamHubBaseUrl, normalizeTeamHubBaseUrl, parseTeamHubJoinDeepLink, parseTeamHubJoinUrl, summarizeInvitationAccess, type InvitationLinkParams } from './invitationLinks.js';
 export type { AdminEntityConfig, AdminResourceOption, CollectionRecord, CreateCollectionInput, CreateEnvironmentInput, CreateFolderInput, CreateHubTokenInput, CreateHubUserInput, CreateInvitedHubUserInput, CreateUserInvitationInput, CreateRequestInput, CreateRunResultInput, CreateSnippetInput, CreatedHubToken, CreatedHubUser, CreatedInvitedHubUser, EnvironmentRecord, FolderRecord, HealthResponse, HubApiTokenRecord, HubInvitationPreview, HubInvitationPreviewUser, HubInvitationRecord, HubInvitationStatus, HubUserRecord, HubUserRole, MoveRequestInput, PluginSourcesResponse, PreviewHubInvitationInput, RedeemHubInvitationInput, RenameFolderInput, ReorderFoldersInput, ReorderRequestsInput, ReloadConfigResponse, ReloadConfigSectionResult, ReloadConfigSectionName, ReloadConfigSectionStatus, RunResultDetail, RunResultKind, RunResultRecord, RunResultSummaryCounts, SavedRequestRecord, SessionCapabilities, SessionResponse, SnippetRecord, SnippetScope, TeamHubAdminResourceOptions, TeamHubClientConfig, UpdateCollectionInput, UpdateEnvironmentInput, UpdateHubUserInput, UpdateRequestInput, UpdateSnippetInput } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAC/F,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EACL,mCAAmC,EACnC,aAAa,EACb,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AACxF,OAAO,EAAE,uCAAuC,EAAE,MAAM,8CAA8C,CAAC;AACvG,OAAO,EAAE,iCAAiC,EAAE,MAAM,wCAAwC,CAAC;AAC3F,OAAO,EAAE,+BAA+B,EAAE,MAAM,sCAAsC,CAAC;AACvF,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,EACxB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,yBAAyB,EACzB,eAAe,EACf,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,YAAY,EACZ,2BAA2B,EAC3B,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAC/F,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EACL,mCAAmC,EACnC,aAAa,EACb,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AACxF,OAAO,EAAE,uCAAuC,EAAE,MAAM,8CAA8C,CAAC;AACvG,OAAO,EAAE,iCAAiC,EAAE,MAAM,wCAAwC,CAAC;AAC3F,OAAO,EAAE,+BAA+B,EAAE,MAAM,sCAAsC,CAAC;AACvF,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,EACxB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,yBAAyB,EACzB,eAAe,EACf,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,YAAY,EACZ,2BAA2B,EAC3B,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -4,3 +4,4 @@ export { toTeamHubAuth } from './auth.js';
 export { isTeamHubCollectionDeleteForbiddenError } from './isTeamHubCollectionDeleteForbiddenError.js';
 export { isTeamHubSnippetsUnsupportedError } from './isTeamHubSnippetsUnsupportedError.js';
 export { isTeamHubSnippetsForbiddenError } from './isTeamHubSnippetsForbiddenError.js';
+export { HARBOR_PROTOCOL, INVITATION_CODE_PREFIX, TEAM_HUB_JOIN_QUERY_KEYS, buildTeamHubJoinDeepLink, buildTeamHubJoinUrl, isInvitationCodeFormat, isTeamHubBaseUrl, normalizeTeamHubBaseUrl, parseTeamHubJoinDeepLink, parseTeamHubJoinUrl, summarizeInvitationAccess } from './invitationLinks.js';

package/dist/invitationLinks.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Custom URL scheme registered by HarborClient for deep links from the web.
+ */
+export declare const HARBOR_PROTOCOL = "harborclient";
+/**
+ * Prefix applied to generated invitation secrets.
+ */
+export declare const INVITATION_CODE_PREFIX = "hbi_";
+/**
+ * Query parameter names shared by HTTPS join links and harborclient:// join links.
+ */
+export declare const TEAM_HUB_JOIN_QUERY_KEYS: {
+    readonly url: "url";
+    readonly name: "name";
+    readonly role: "role";
+    readonly exp: "exp";
+    readonly hub: "hub";
+    readonly access: "access";
+    readonly code: "code";
+};
+/**
+ * Fields used to build and parse Team Hub onboarding invitation links.
+ */
+export interface InvitationLinkParams {
+    /**
+     * Team Hub server base URL used for connection and redemption.
+     */
+    baseUrl: string;
+    /**
+     * One-time invitation secret prefixed with `hbi_`.
+     */
+    code: string;
+    /**
+     * Invited user display name shown in confirmation UI.
+     */
+    name: string;
+    /**
+     * Invited user role shown in confirmation UI.
+     */
+    role: 'admin' | 'user';
+    /**
+     * ISO-8601 expiry timestamp for the invitation.
+     */
+    expiresAt: string;
+    /**
+     * Optional friendly hub label shown in confirmation UI.
+     */
+    hubName?: string;
+    /**
+     * Optional human-readable access summary shown in confirmation UI.
+     */
+    accessSummary?: string;
+}
+/**
+ * Returns whether a string looks like a Team Hub invitation secret.
+ *
+ * @param value - Candidate invitation code.
+ */
+export declare function isInvitationCodeFormat(value: string): boolean;
+/**
+ * Returns whether a string is a valid HTTP or HTTPS Team Hub base URL.
+ *
+ * @param value - Candidate Team Hub base URL.
+ */
+export declare function isTeamHubBaseUrl(value: string): boolean;
+/**
+ * Normalizes a Team Hub base URL by trimming and removing trailing slashes.
+ *
+ * @param baseUrl - Raw Team Hub base URL.
+ */
+export declare function normalizeTeamHubBaseUrl(baseUrl: string): string;
+/**
+ * Builds an HTTPS join link with display info in the query string and the
+ * invitation secret in the URL fragment.
+ *
+ * @param params - Invitation link parameters.
+ * @returns Clickable HTTPS join URL suitable for email and chat delivery.
+ */
+export declare function buildTeamHubJoinUrl(params: InvitationLinkParams): string;
+/**
+ * Parses an HTTPS Team Hub join link into invitation parameters.
+ *
+ * @param url - Raw HTTPS join URL from a browser or pasted invite link.
+ * @returns Parsed invitation parameters, or null when invalid.
+ */
+export declare function parseTeamHubJoinUrl(url: string): InvitationLinkParams | null;
+/**
+ * Builds a harborclient:// join deep link with the invitation secret in the query.
+ *
+ * @param params - Invitation link parameters.
+ * @returns Deep link URL suitable for launching HarborClient.
+ */
+export declare function buildTeamHubJoinDeepLink(params: InvitationLinkParams): string;
+/**
+ * Parses a harborclient:// Team Hub join deep link into invitation parameters.
+ *
+ * @param url - Raw harborclient:// join URL from the OS protocol handler.
+ * @returns Parsed invitation parameters, or null when invalid.
+ */
+export declare function parseTeamHubJoinDeepLink(url: string): InvitationLinkParams | null;
+/**
+ * Builds a short human-readable access summary from hub user access lists.
+ *
+ * @param input - Access list fields from a hub user record.
+ * @returns Summary string suitable for invite link query parameters.
+ */
+export declare function summarizeInvitationAccess(input: {
+    collectionAccess: string[];
+    environmentAccess: string[];
+    snippetAccess: string[];
+    llmAccess: boolean;
+    llmModels: string[];
+}): string;
+//# sourceMappingURL=invitationLinks.d.ts.map

package/dist/invitationLinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invitationLinks.d.ts","sourceRoot":"","sources":["../src/invitationLinks.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAE9C;;GAEG;AACH,eAAO,MAAM,sBAAsB,SAAS,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;CAQ3B,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAI7D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOvD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/D;AAgED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAOxE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CA8B5E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAI7E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CA2BjF;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB,GAAG,MAAM,CAcT"}

package/dist/invitationLinks.js

@@ -0,0 +1,222 @@
+/**
+ * Custom URL scheme registered by HarborClient for deep links from the web.
+ */
+export const HARBOR_PROTOCOL = 'harborclient';
+/**
+ * Prefix applied to generated invitation secrets.
+ */
+export const INVITATION_CODE_PREFIX = 'hbi_';
+/**
+ * Query parameter names shared by HTTPS join links and harborclient:// join links.
+ */
+export const TEAM_HUB_JOIN_QUERY_KEYS = {
+    url: 'url',
+    name: 'name',
+    role: 'role',
+    exp: 'exp',
+    hub: 'hub',
+    access: 'access',
+    code: 'code'
+};
+/**
+ * Returns whether a string looks like a Team Hub invitation secret.
+ *
+ * @param value - Candidate invitation code.
+ */
+export function isInvitationCodeFormat(value) {
+    return (value.startsWith(INVITATION_CODE_PREFIX) && value.length > INVITATION_CODE_PREFIX.length + 8);
+}
+/**
+ * Returns whether a string is a valid HTTP or HTTPS Team Hub base URL.
+ *
+ * @param value - Candidate Team Hub base URL.
+ */
+export function isTeamHubBaseUrl(value) {
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Normalizes a Team Hub base URL by trimming and removing trailing slashes.
+ *
+ * @param baseUrl - Raw Team Hub base URL.
+ */
+export function normalizeTeamHubBaseUrl(baseUrl) {
+    return baseUrl.trim().replace(/\/+$/, '');
+}
+/**
+ * Builds the non-secret query string shared by HTTPS and deep links.
+ *
+ * @param params - Invitation link parameters.
+ */
+function buildJoinQueryParams(params) {
+    const query = new URLSearchParams({
+        [TEAM_HUB_JOIN_QUERY_KEYS.url]: normalizeTeamHubBaseUrl(params.baseUrl),
+        [TEAM_HUB_JOIN_QUERY_KEYS.name]: params.name.trim(),
+        [TEAM_HUB_JOIN_QUERY_KEYS.role]: params.role,
+        [TEAM_HUB_JOIN_QUERY_KEYS.exp]: params.expiresAt
+    });
+    if (params.hubName?.trim()) {
+        query.set(TEAM_HUB_JOIN_QUERY_KEYS.hub, params.hubName.trim());
+    }
+    if (params.accessSummary?.trim()) {
+        query.set(TEAM_HUB_JOIN_QUERY_KEYS.access, params.accessSummary.trim());
+    }
+    return query;
+}
+/**
+ * Parses shared invitation link query parameters into {@link InvitationLinkParams}.
+ *
+ * @param query - Parsed query string from an HTTPS or deep link.
+ * @param code - Invitation secret from the fragment or query string.
+ */
+function parseJoinQueryParams(query, code) {
+    const baseUrl = query.get(TEAM_HUB_JOIN_QUERY_KEYS.url)?.trim();
+    const name = query.get(TEAM_HUB_JOIN_QUERY_KEYS.name)?.trim();
+    const role = query.get(TEAM_HUB_JOIN_QUERY_KEYS.role)?.trim();
+    const expiresAt = query.get(TEAM_HUB_JOIN_QUERY_KEYS.exp)?.trim();
+    if (!baseUrl || !name || !role || !expiresAt || !isTeamHubBaseUrl(baseUrl)) {
+        return null;
+    }
+    if (role !== 'admin' && role !== 'user') {
+        return null;
+    }
+    if (!isInvitationCodeFormat(code)) {
+        return null;
+    }
+    const hubName = query.get(TEAM_HUB_JOIN_QUERY_KEYS.hub)?.trim();
+    const accessSummary = query.get(TEAM_HUB_JOIN_QUERY_KEYS.access)?.trim();
+    return {
+        baseUrl: normalizeTeamHubBaseUrl(baseUrl),
+        code,
+        name,
+        role,
+        expiresAt,
+        hubName: hubName || undefined,
+        accessSummary: accessSummary || undefined
+    };
+}
+/**
+ * Builds an HTTPS join link with display info in the query string and the
+ * invitation secret in the URL fragment.
+ *
+ * @param params - Invitation link parameters.
+ * @returns Clickable HTTPS join URL suitable for email and chat delivery.
+ */
+export function buildTeamHubJoinUrl(params) {
+    const baseUrl = normalizeTeamHubBaseUrl(params.baseUrl);
+    const query = buildJoinQueryParams(params);
+    const fragment = new URLSearchParams({
+        [TEAM_HUB_JOIN_QUERY_KEYS.code]: params.code.trim()
+    });
+    return `${baseUrl}/join?${query.toString()}#${fragment.toString()}`;
+}
+/**
+ * Parses an HTTPS Team Hub join link into invitation parameters.
+ *
+ * @param url - Raw HTTPS join URL from a browser or pasted invite link.
+ * @returns Parsed invitation parameters, or null when invalid.
+ */
+export function parseTeamHubJoinUrl(url) {
+    const trimmed = url.trim();
+    if (!trimmed) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return null;
+    }
+    if (!parsed.pathname.endsWith('/join')) {
+        return null;
+    }
+    const fragmentParams = new URLSearchParams(parsed.hash.startsWith('#') ? parsed.hash.slice(1) : parsed.hash);
+    const code = fragmentParams.get(TEAM_HUB_JOIN_QUERY_KEYS.code)?.trim();
+    if (!code) {
+        return null;
+    }
+    return parseJoinQueryParams(parsed.searchParams, code);
+}
+/**
+ * Builds a harborclient:// join deep link with the invitation secret in the query.
+ *
+ * @param params - Invitation link parameters.
+ * @returns Deep link URL suitable for launching HarborClient.
+ */
+export function buildTeamHubJoinDeepLink(params) {
+    const query = buildJoinQueryParams(params);
+    query.set(TEAM_HUB_JOIN_QUERY_KEYS.code, params.code.trim());
+    return `${HARBOR_PROTOCOL}://team-hub/join?${query.toString()}`;
+}
+/**
+ * Parses a harborclient:// Team Hub join deep link into invitation parameters.
+ *
+ * @param url - Raw harborclient:// join URL from the OS protocol handler.
+ * @returns Parsed invitation parameters, or null when invalid.
+ */
+export function parseTeamHubJoinDeepLink(url) {
+    const trimmed = url.trim();
+    if (!trimmed) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== `${HARBOR_PROTOCOL}:`) {
+        return null;
+    }
+    if (parsed.hostname !== 'team-hub' || parsed.pathname !== '/join') {
+        return null;
+    }
+    const code = parsed.searchParams.get(TEAM_HUB_JOIN_QUERY_KEYS.code)?.trim();
+    if (!code) {
+        return null;
+    }
+    return parseJoinQueryParams(parsed.searchParams, code);
+}
+/**
+ * Builds a short human-readable access summary from hub user access lists.
+ *
+ * @param input - Access list fields from a hub user record.
+ * @returns Summary string suitable for invite link query parameters.
+ */
+export function summarizeInvitationAccess(input) {
+    const parts = [];
+    parts.push(`Collections: ${formatAccessList(input.collectionAccess)}`);
+    parts.push(`Environments: ${formatAccessList(input.environmentAccess)}`);
+    parts.push(`Snippets: ${formatAccessList(input.snippetAccess)}`);
+    if (input.llmAccess) {
+        parts.push(`LLM: ${formatAccessList(input.llmModels)}`);
+    }
+    else {
+        parts.push('LLM: disabled');
+    }
+    return parts.join(' · ');
+}
+/**
+ * Formats one access list for display in invite summaries.
+ *
+ * @param values - Access list values from a hub user record.
+ */
+function formatAccessList(values) {
+    if (values.includes('*')) {
+        return 'all';
+    }
+    if (values.length === 0) {
+        return 'none';
+    }
+    return values.join(', ');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harborclient/team-hub-api",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "TypeScript client for the HarborClient Team Hub API.",
   "keywords": [
     "harborclient",