@geniee-inc/sfa-kit 1.6.0 → 1.7.1

package/GUIDE.md

@@ -570,6 +570,68 @@ export default function Page() {
 }
 ```
 
+## Record detail links (opt-in)
+
+Open the standard SFA/CRM record detail page (詳細 tab) for a record. Links are generated on demand. The kit does not add them automatically. Use only when the user asks for clickable record names, detail links, or navigation to the full record view.
+
+### useRecordDetailUrl
+
+Returns a link to the record detail page, or `null` when unavailable (standalone preview, no host detected, or unsupported collection such as `schedules`).
+
+```tsx
+import { useRecordDetailUrl } from '@geniee-inc/sfa-kit';
+
+function CompanyRow({ record }: { record: SfaRecord }) {
+  const link = useRecordDetailUrl(record.collection_name, record.record_id);
+
+  return (
+    <tr>
+      <td>
+        {link ? (
+          <a href={link.url} target={link.target}>
+            {record.title ?? record.record_id}
+          </a>
+        ) : (
+          record.title ?? record.record_id
+        )}
+      </td>
+    </tr>
+  );
+}
+```
+
+Returns `{ url: string, target: '_blank' } | null`.
+
+- `target` is always `'_blank'` so the record detail page opens in a new browser tab, preserving the user's current Studio page.
+- Returns `null` in standalone preview mode (no host origin to build a URL from), when no `organizationId` is in context, or when the collection does not have a standard record page (e.g. `schedules`).
+
+### buildRecordDetailUrl (advanced)
+
+Pure function for building the URL manually when you need full control over the parameters.
+
+```tsx
+import { buildRecordDetailUrl } from '@geniee-inc/sfa-kit';
+
+const url = buildRecordDetailUrl({
+  hostOrigin: 'https://app.chikyu.net',
+  organizationId: '12324',
+  collectionName: 'companies',
+  recordId: '6a7d9baf07dd37e8d464f2cf',
+});
+// -> 'https://app.chikyu.net/org/12324/company/record/6a7d9baf07dd37e8d464f2cf'
+
+// Custom objects
+const customUrl = buildRecordDetailUrl({
+  hostOrigin: 'https://app.chikyu.net',
+  organizationId: '12324',
+  collectionName: 'waste_collection_routes',
+  recordId: 'b3e1f8c204aa59d7e612a0b1',
+});
+// -> 'https://app.chikyu.net/org/12324/custom_object/waste_collection_routes/record/b3e1f8c204aa59d7e612a0b1'
+```
+
+Returns `null` for unsupported collections (e.g. `schedules`).
+
 ## Do NOT
 
 - Do NOT create your own authentication, login forms, or auth providers. `SfaLoginGate` handles everything.
@@ -579,6 +641,7 @@ export default function Page() {
 - Do NOT call the API directly with fetch. Use the provided hooks or `useSfaClient()`.
 - Do NOT add Route Handlers (app/api/) for SFA data. The kit calls the API from the browser.
 - Do NOT hardcode API base URLs, API keys, or credentials anywhere.
+- Do NOT add record detail links automatically. They are opt-in: generate them only when the user asks (e.g. "make the names clickable", "add links to records"), or ask the user for confirmation before adding them. In standalone preview mode, links are unavailable (`useRecordDetailUrl` returns `null`). The `schedules` collection does not have a standard record detail page; if asked, tell the user that schedule links are not yet supported.
 - Do NOT import from `@mui/material`, `@emotion`, or `@ag-grid`. This package has zero external UI dependencies.
 - Do NOT nest SfaLoginGate inside another SfaLoginGate or SfaProvider.
 - Do NOT hardcode a list of available objects. Discover from the user's request or `useDescribe`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geniee-inc/sfa-kit",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "React hooks and components for building pages that connect to GENIEE SFA/CRM data.",
   "type": "module",
   "main": "./src/index.js",

package/src/index.d.ts

@@ -27,3 +27,6 @@ export { ErrorBoundary } from './lib/components/ErrorBoundary';
 export { EmptyState } from './lib/components/EmptyState';
 export type { SfaAuth, SfaApiMode, SfaClientConfig, SfaRecord, SfaListResponse, SfaListParams, SfaFieldValue, SfaFieldKind, SfaFieldValueMapping, FieldGroupSpec, FieldGroupLayout, SfaFieldDescriptor, SfaFieldOption, SfaRelationDescriptor, SfaObjectDetail, SfaObjectSummary, SfaObjectCatalog, SfaObjectPermissions, SfaObjectOrigin, SfaRelationshipKind, SfaCardinality, SfaDescribeResult, SfaFieldTypeDescriptor, SfaFieldTypeCatalog, SfaFilterOperator, SfaCreateOptions, SfaFieldError, } from './lib/provider/types';
 export type { SfaSession, AuthResult, OrganizationChoice, } from './lib/auth/types';
+export { buildRecordDetailUrl, resolveHostOrigin, } from './lib/navigation/record-detail-url';
+export type { RecordDetailUrlParams, RecordDetailLink, } from './lib/navigation/record-detail-url';
+export { useRecordDetailUrl } from './lib/hooks/useRecordDetailUrl';

package/src/index.js

@@ -19,3 +19,5 @@ export { RecordView } from './lib/components/RecordView';
 export { RecordList } from './lib/components/RecordList';
 export { ErrorBoundary } from './lib/components/ErrorBoundary';
 export { EmptyState } from './lib/components/EmptyState';
+export { buildRecordDetailUrl, resolveHostOrigin, } from './lib/navigation/record-detail-url';
+export { useRecordDetailUrl } from './lib/hooks/useRecordDetailUrl';

package/src/lib/hooks/useRecordDetailUrl.d.ts

@@ -0,0 +1,22 @@
+import type { RecordDetailLink } from '../navigation/record-detail-url';
+/**
+ * @description Returns a link to the SFA/CRM record detail page (詳細 tab),
+ * or `null` when unavailable (standalone preview, missing org ID, or
+ * unsupported collection like `schedules`).
+ *
+ * Reads the organization ID from `SfaContext` and the host origin from
+ * `document.referrer` (the SFA parent frame). No configuration needed.
+ *
+ * The returned `target` is always `'_blank'` so the record opens in a new
+ * browser tab, preserving the user's current Studio page context.
+ *
+ * @example
+ * ```tsx
+ * const link = useRecordDetailUrl('companies', 'rec-123');
+ * if (link) {
+ *   return <a href={link.url} target={link.target}>{name}</a>;
+ * }
+ * return <span>{name}</span>;
+ * ```
+ */
+export declare function useRecordDetailUrl(collectionName: string, recordId: string): RecordDetailLink | null;

package/src/lib/hooks/useRecordDetailUrl.js

@@ -0,0 +1,42 @@
+import { useMemo } from 'react';
+import { buildRecordDetailUrl, resolveHostOrigin, } from '../navigation/record-detail-url';
+import { useSfaContext } from '../provider/useSfaClient';
+/**
+ * @description Returns a link to the SFA/CRM record detail page (詳細 tab),
+ * or `null` when unavailable (standalone preview, missing org ID, or
+ * unsupported collection like `schedules`).
+ *
+ * Reads the organization ID from `SfaContext` and the host origin from
+ * `document.referrer` (the SFA parent frame). No configuration needed.
+ *
+ * The returned `target` is always `'_blank'` so the record opens in a new
+ * browser tab, preserving the user's current Studio page context.
+ *
+ * @example
+ * ```tsx
+ * const link = useRecordDetailUrl('companies', 'rec-123');
+ * if (link) {
+ *   return <a href={link.url} target={link.target}>{name}</a>;
+ * }
+ * return <span>{name}</span>;
+ * ```
+ */
+export function useRecordDetailUrl(collectionName, recordId) {
+    const { organizationId } = useSfaContext();
+    return useMemo(() => {
+        const hostOrigin = resolveHostOrigin();
+        if (hostOrigin == null || organizationId == null) {
+            return null;
+        }
+        const url = buildRecordDetailUrl({
+            hostOrigin,
+            organizationId,
+            collectionName,
+            recordId,
+        });
+        if (url == null) {
+            return null;
+        }
+        return { url, target: '_blank' };
+    }, [organizationId, collectionName, recordId]);
+}

package/src/lib/navigation/record-detail-url.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @description Builds URLs for SFA/CRM record detail pages (詳細 tab).
+ *
+ * The URL pattern varies between standard objects (singular route key) and
+ * custom objects (collection name in a `/custom_object/` segment). This
+ * module encapsulates that mapping so callers only need a collection name,
+ * record ID, host origin, and organization ID.
+ *
+ * Source of truth for the standard-object route map:
+ *   apps/axiom-web/src/pages/org/[organizationId]/[singularName]/record/[recordId].tsx
+ *   and DEFAULT_COLLECTION_NAME_REV_MAP in axiom-web.
+ */
+export interface RecordDetailUrlParams {
+    /** The SFA/CRM host origin (e.g. "https://app.chikyu.net"). */
+    readonly hostOrigin: string;
+    /** The organization ID the record belongs to. */
+    readonly organizationId: string;
+    /** The plural collection name (e.g. "companies", "business_discussions"). */
+    readonly collectionName: string;
+    /** The record's unique ID. */
+    readonly recordId: string;
+}
+export interface RecordDetailLink {
+    /** The full URL to the record detail page. */
+    readonly url: string;
+    /**
+     * Suggested link target. Always `'_blank'` so the record detail page opens
+     * in a new browser tab, preserving the user's current Studio page context.
+     * The SFA iframe sandbox includes `allow-popups` to permit this.
+     */
+    readonly target: '_blank';
+}
+/**
+ * @description Builds the full URL for a record's detail page in SFA/CRM.
+ *
+ * Returns `null` when the collection is not supported (e.g. `schedules`).
+ *
+ * Standard objects use: `{hostOrigin}/org/{orgId}/{singularKey}/record/{recordId}`
+ * Custom objects use:   `{hostOrigin}/org/{orgId}/custom_object/{collectionName}/record/{recordId}`
+ */
+export declare function buildRecordDetailUrl(params: RecordDetailUrlParams): string | null;
+/**
+ * @description Resolves the SFA/CRM host origin from the embedding context.
+ *
+ * In embed mode (page running inside an SFA iframe), `document.referrer`
+ * contains the parent page's URL, from which we extract the origin.
+ * This is the same pattern used by `resolveTrustedOrigin` in SfaLoginGate.
+ *
+ * Returns `null` when:
+ * - Running in SSR (no `window`)
+ * - Not running inside an iframe (standalone mode)
+ * - The referrer is empty or malformed
+ */
+export declare function resolveHostOrigin(): string | null;

package/src/lib/navigation/record-detail-url.js

@@ -0,0 +1,112 @@
+/**
+ * @description Builds URLs for SFA/CRM record detail pages (詳細 tab).
+ *
+ * The URL pattern varies between standard objects (singular route key) and
+ * custom objects (collection name in a `/custom_object/` segment). This
+ * module encapsulates that mapping so callers only need a collection name,
+ * record ID, host origin, and organization ID.
+ *
+ * Source of truth for the standard-object route map:
+ *   apps/axiom-web/src/pages/org/[organizationId]/[singularName]/record/[recordId].tsx
+ *   and DEFAULT_COLLECTION_NAME_REV_MAP in axiom-web.
+ */
+/**
+ * Maps standard (default) collection names (plural) to their singular URL
+ * route key used in axiom-web's `/org/{orgId}/{singularKey}/record/{recordId}`
+ * route.
+ *
+ * Sync reference: `DEFAULT_COLLECTION_NAME_REV_MAP` in axiom-web.
+ * This list changes only when SFA adds new default object types.
+ */
+const STANDARD_OBJECT_ROUTE_MAP = {
+    business_discussions: 'business_discussion',
+    companies: 'company',
+    customers: 'customer',
+    prospects: 'prospect',
+    activity_histories: 'activity_history',
+    tasks: 'task',
+    merchandises: 'merchandise',
+    opportunity_merchandises: 'opportunity_merchandise',
+    // Alt objects (ALT_COLLECTION_NAME_REV_MAP in axiom-web)
+    projects: 'project',
+};
+/**
+ * Collections that have no standard record detail page. `buildRecordDetailUrl`
+ * returns `null` for these.
+ *
+ * - `schedules`: uses a query-param based URL (`/schedule?selectedSchedule=...`),
+ *   not the standard `/record/{id}` pattern. Support may be added later.
+ */
+const UNSUPPORTED_COLLECTIONS = new Set(['schedules']);
+/**
+ * @description Builds the full URL for a record's detail page in SFA/CRM.
+ *
+ * Returns `null` when the collection is not supported (e.g. `schedules`).
+ *
+ * Standard objects use: `{hostOrigin}/org/{orgId}/{singularKey}/record/{recordId}`
+ * Custom objects use:   `{hostOrigin}/org/{orgId}/custom_object/{collectionName}/record/{recordId}`
+ */
+export function buildRecordDetailUrl(params) {
+    const { hostOrigin, organizationId, collectionName, recordId } = params;
+    if (UNSUPPORTED_COLLECTIONS.has(collectionName)) {
+        return null;
+    }
+    let origin;
+    try {
+        const parsed = new URL(hostOrigin);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            return null;
+        }
+        origin = parsed.origin;
+    }
+    catch (_a) {
+        return null;
+    }
+    const singularKey = STANDARD_OBJECT_ROUTE_MAP[collectionName];
+    if (singularKey != null) {
+        return `${origin}/org/${encodeURIComponent(organizationId)}/${singularKey}/record/${encodeURIComponent(recordId)}`;
+    }
+    // Custom object
+    return `${origin}/org/${encodeURIComponent(organizationId)}/custom_object/${encodeURIComponent(collectionName)}/record/${encodeURIComponent(recordId)}`;
+}
+/**
+ * @description Resolves the SFA/CRM host origin from the embedding context.
+ *
+ * In embed mode (page running inside an SFA iframe), `document.referrer`
+ * contains the parent page's URL, from which we extract the origin.
+ * This is the same pattern used by `resolveTrustedOrigin` in SfaLoginGate.
+ *
+ * Returns `null` when:
+ * - Running in SSR (no `window`)
+ * - Not running inside an iframe (standalone mode)
+ * - The referrer is empty or malformed
+ */
+export function resolveHostOrigin() {
+    try {
+        if (typeof window === 'undefined')
+            return null;
+        // Only resolve when running inside an iframe. In standalone mode,
+        // document.referrer may contain an external origin (e.g. the page
+        // that navigated here), which would produce incorrect links.
+        if (window.parent === window)
+            return null;
+        const referrer = document.referrer;
+        if (!referrer)
+            return null;
+        return new URL(referrer).origin;
+    }
+    catch (_a) {
+        // Cross-origin window.parent access throws (embedded), or malformed referrer
+        // If we can't access window.parent, we're in a cross-origin iframe,
+        // so fall through to read the referrer.
+    }
+    try {
+        const referrer = document.referrer;
+        if (!referrer)
+            return null;
+        return new URL(referrer).origin;
+    }
+    catch (_b) {
+        return null;
+    }
+}

package/src/lib/version.d.ts

@@ -1 +1 @@
-export declare const SFA_KIT_VERSION = "1.6.0";
+export declare const SFA_KIT_VERSION = "1.7.1";

package/src/lib/version.js

@@ -1 +1,3 @@
-export const SFA_KIT_VERSION = "1.6.0";
+// このファイルは libs/sfa-kit/scripts/sync-version.cjs が生成する。
+// 手で編集しないこと。バージョンを上げるときは libs/sfa-kit/package.json を変更する。
+export const SFA_KIT_VERSION = '1.7.1';