@treeviz/familysearch-sdk 1.0.13 → 1.0.15

package/README.md

@@ -15,6 +15,7 @@ A modern, TypeScript-first SDK for the FamilySearch API v3.
 - 📝 **GEDCOM export** - Convert FamilySearch data to GEDCOM 5.5 format
 - 📍 **Places API** helpers for location searches
 - 👨‍👩‍👧 **Tree/Pedigree API** for ancestry data
+- 📚 **Sources API** - Fetch source references linked to persons
 
 ## Installation
 
@@ -131,6 +132,36 @@ const pedigree = await fetchPedigree(sdk, undefined, {
 });
 ```
 
+## Sources API
+
+Retrieve source references linked to persons.
+
+```typescript
+import { createFamilySearchSDK } from 'familysearch-sdk';
+
+const sdk = createFamilySearchSDK({ accessToken: 'token' });
+
+// Fetch sources for a person
+const sources = await sdk.getPersonSources('KWQS-BBQ');
+
+// Access source references
+if (sources?.persons?.[0]?.sources) {
+  sources.persons[0].sources.forEach(source => {
+    console.log('Source ID:', source.descriptionId);
+    console.log('Qualifiers:', source.qualifiers);
+  });
+}
+
+// Access source descriptions
+if (sources?.sourceDescriptions) {
+  sources.sourceDescriptions.forEach(desc => {
+    console.log('Title:', desc.titles?.[0]?.value);
+    console.log('Citation:', desc.citations?.[0]?.value);
+    console.log('About:', desc.about);
+  });
+}
+```
+
 ## GEDCOM Conversion
 
 Convert FamilySearch data to GEDCOM 5.5 format.
@@ -218,6 +249,10 @@ const sdk = createFamilySearchSDK({
 - `getPersonWithDetails(sdk, personId)` - Get person details
 - `fetchMultiplePersons(sdk, personIds)` - Batch fetch persons
 
+### Person Sources
+
+- `sdk.getPersonSources(personId)` - Get source references for a person
+
 ### Utils (`/utils`)
 
 - `convertToGedcom(pedigreeData, options)` - Convert to GEDCOM

package/dist/auth/index.d.cts

@@ -1,4 +1,4 @@
-import { F as FamilySearchEnvironment, s as OAuthEndpoints, t as OAuthConfig, O as OAuthTokenResponse, u as OAuthStateValidation } from '../index-D6H-lvis.cjs';
+import { F as FamilySearchEnvironment, x as OAuthEndpoints, y as OAuthConfig, O as OAuthTokenResponse, z as OAuthStateValidation } from '../index-jdvA0fPb.cjs';
 
 /**
  * FamilySearch OAuth Authentication Module

package/dist/auth/index.d.ts

@@ -1,4 +1,4 @@
-import { F as FamilySearchEnvironment, s as OAuthEndpoints, t as OAuthConfig, O as OAuthTokenResponse, u as OAuthStateValidation } from '../index-D6H-lvis.js';
+import { F as FamilySearchEnvironment, x as OAuthEndpoints, y as OAuthConfig, O as OAuthTokenResponse, z as OAuthStateValidation } from '../index-jdvA0fPb.js';
 
 /**
  * FamilySearch OAuth Authentication Module

package/dist/{client-ohjqX4t5.d.cts → client-C9fvn-wZ.d.cts}

@@ -1,4 +1,4 @@
-import { a as FamilySearchSDKConfig, F as FamilySearchEnvironment, E as EnvironmentConfig, b as FamilySearchApiResponse, d as FamilySearchUser, e as FamilySearchPerson, i as PersonWithRelationships, j as PersonNotesResponse, w as PersonMemoriesResponse, h as RelationshipDetails, p as PedigreeData, x as PersonSearchResponse, k as FamilySearchPlace } from './index-D6H-lvis.cjs';
+import { a as FamilySearchSDKConfig, F as FamilySearchEnvironment, E as EnvironmentConfig, b as FamilySearchApiResponse, d as FamilySearchUser, e as FamilySearchPerson, i as PersonWithRelationships, j as PersonNotesResponse, k as PersonMemoriesResponse, m as PersonSourcesResponse, h as RelationshipDetails, u as PedigreeData, l as PersonSearchResponse, p as FamilySearchPlace } from './index-jdvA0fPb.cjs';
 
 /**
  * FamilySearch SDK Client
@@ -98,6 +98,24 @@ declare class FamilySearchSDK {
      * Get memories for a person
      */
     getPersonMemories(personId: string): Promise<PersonMemoriesResponse | null>;
+    /**
+     * Get sources for a person
+     * Fetches all source references linked to a person
+     *
+     * @param personId - FamilySearch person ID
+     * @returns Person sources response with source references and descriptions, or null if error
+     *
+     * @example
+     * ```typescript
+     * const sources = await sdk.getPersonSources('KWQS-BBQ');
+     * if (sources?.persons?.[0]?.sources) {
+     *   sources.persons[0].sources.forEach(source => {
+     *     console.log('Source:', source.descriptionId);
+     *   });
+     * }
+     * ```
+     */
+    getPersonSources(personId: string): Promise<PersonSourcesResponse | null>;
     /**
      * Get couple relationship details
      */

package/dist/{client-DIpYSHtx.d.ts → client-DYad9DOD.d.ts}

@@ -1,4 +1,4 @@
-import { a as FamilySearchSDKConfig, F as FamilySearchEnvironment, E as EnvironmentConfig, b as FamilySearchApiResponse, d as FamilySearchUser, e as FamilySearchPerson, i as PersonWithRelationships, j as PersonNotesResponse, w as PersonMemoriesResponse, h as RelationshipDetails, p as PedigreeData, x as PersonSearchResponse, k as FamilySearchPlace } from './index-D6H-lvis.js';
+import { a as FamilySearchSDKConfig, F as FamilySearchEnvironment, E as EnvironmentConfig, b as FamilySearchApiResponse, d as FamilySearchUser, e as FamilySearchPerson, i as PersonWithRelationships, j as PersonNotesResponse, k as PersonMemoriesResponse, m as PersonSourcesResponse, h as RelationshipDetails, u as PedigreeData, l as PersonSearchResponse, p as FamilySearchPlace } from './index-jdvA0fPb.js';
 
 /**
  * FamilySearch SDK Client
@@ -98,6 +98,24 @@ declare class FamilySearchSDK {
      * Get memories for a person
      */
     getPersonMemories(personId: string): Promise<PersonMemoriesResponse | null>;
+    /**
+     * Get sources for a person
+     * Fetches all source references linked to a person
+     *
+     * @param personId - FamilySearch person ID
+     * @returns Person sources response with source references and descriptions, or null if error
+     *
+     * @example
+     * ```typescript
+     * const sources = await sdk.getPersonSources('KWQS-BBQ');
+     * if (sources?.persons?.[0]?.sources) {
+     *   sources.persons[0].sources.forEach(source => {
+     *     console.log('Source:', source.descriptionId);
+     *   });
+     * }
+     * ```
+     */
+    getPersonSources(personId: string): Promise<PersonSourcesResponse | null>;
     /**
      * Get couple relationship details
      */

package/dist/{index-D6H-lvis.d.cts → index-jdvA0fPb.d.cts}

@@ -386,6 +386,7 @@ interface PersonNotesResponse {
 interface EnhancedPerson extends PersonData {
     fullDetails?: PersonWithRelationships;
     notes?: PersonNotesResponse;
+    sources?: PersonSourcesResponse;
 }
 /**
  * Person with relationships response from getPersonWithDetails API
@@ -422,6 +423,21 @@ interface SourceReference {
         value: string;
     }>;
 }
+/**
+ * Person sources response from FamilySearch API
+ * Returned by GET /platform/tree/persons/{personId}/sources
+ */
+interface PersonSourcesResponse {
+    /** Array of persons with their sources */
+    persons?: Array<{
+        /** Person ID */
+        id?: string;
+        /** Source references attached to the person */
+        sources?: SourceReference[];
+    }>;
+    /** Source descriptions providing details about sources */
+    sourceDescriptions?: SourceDescription[];
+}
 /**
  * Enhanced pedigree with full details
  */
@@ -481,4 +497,4 @@ type ProgressCallback = (progress: {
     percent: number;
 }) => void;
 
-export type { ChildAndParentsRelationship as C, EnvironmentConfig as E, FamilySearchEnvironment as F, NameForm as N, OAuthTokenResponse as O, PersonDisplay as P, Relationship as R, SDKLogger as S, FamilySearchSDKConfig as a, FamilySearchApiResponse as b, FamilySearchApiError as c, FamilySearchUser as d, FamilySearchPerson as e, PersonFact as f, PersonData as g, RelationshipDetails as h, PersonWithRelationships as i, PersonNotesResponse as j, FamilySearchPlace as k, PlaceDescription as l, PlaceSearchResult as m, PlaceSearchResponse as n, PlaceDetailsResponse as o, PedigreeData as p, EnhancedPerson as q, EnhancedPedigreeData as r, OAuthEndpoints as s, OAuthConfig as t, OAuthStateValidation as u, ProgressCallback as v, PersonMemoriesResponse as w, PersonSearchResponse as x };
+export type { ProgressCallback as A, ChildAndParentsRelationship as C, EnvironmentConfig as E, FamilySearchEnvironment as F, NameForm as N, OAuthTokenResponse as O, PersonDisplay as P, Relationship as R, SDKLogger as S, FamilySearchSDKConfig as a, FamilySearchApiResponse as b, FamilySearchApiError as c, FamilySearchUser as d, FamilySearchPerson as e, PersonFact as f, PersonData as g, RelationshipDetails as h, PersonWithRelationships as i, PersonNotesResponse as j, PersonMemoriesResponse as k, PersonSearchResponse as l, PersonSourcesResponse as m, SourceDescription as n, SourceReference as o, FamilySearchPlace as p, PlaceDescription as q, PlaceSearchResult as r, PlaceSearchResponse as s, PlaceDetailsResponse as t, PedigreeData as u, EnhancedPerson as v, EnhancedPedigreeData as w, OAuthEndpoints as x, OAuthConfig as y, OAuthStateValidation as z };

package/dist/{index-D6H-lvis.d.ts → index-jdvA0fPb.d.ts}

@@ -386,6 +386,7 @@ interface PersonNotesResponse {
 interface EnhancedPerson extends PersonData {
     fullDetails?: PersonWithRelationships;
     notes?: PersonNotesResponse;
+    sources?: PersonSourcesResponse;
 }
 /**
  * Person with relationships response from getPersonWithDetails API
@@ -422,6 +423,21 @@ interface SourceReference {
         value: string;
     }>;
 }
+/**
+ * Person sources response from FamilySearch API
+ * Returned by GET /platform/tree/persons/{personId}/sources
+ */
+interface PersonSourcesResponse {
+    /** Array of persons with their sources */
+    persons?: Array<{
+        /** Person ID */
+        id?: string;
+        /** Source references attached to the person */
+        sources?: SourceReference[];
+    }>;
+    /** Source descriptions providing details about sources */
+    sourceDescriptions?: SourceDescription[];
+}
 /**
  * Enhanced pedigree with full details
  */
@@ -481,4 +497,4 @@ type ProgressCallback = (progress: {
     percent: number;
 }) => void;
 
-export type { ChildAndParentsRelationship as C, EnvironmentConfig as E, FamilySearchEnvironment as F, NameForm as N, OAuthTokenResponse as O, PersonDisplay as P, Relationship as R, SDKLogger as S, FamilySearchSDKConfig as a, FamilySearchApiResponse as b, FamilySearchApiError as c, FamilySearchUser as d, FamilySearchPerson as e, PersonFact as f, PersonData as g, RelationshipDetails as h, PersonWithRelationships as i, PersonNotesResponse as j, FamilySearchPlace as k, PlaceDescription as l, PlaceSearchResult as m, PlaceSearchResponse as n, PlaceDetailsResponse as o, PedigreeData as p, EnhancedPerson as q, EnhancedPedigreeData as r, OAuthEndpoints as s, OAuthConfig as t, OAuthStateValidation as u, ProgressCallback as v, PersonMemoriesResponse as w, PersonSearchResponse as x };
+export type { ProgressCallback as A, ChildAndParentsRelationship as C, EnvironmentConfig as E, FamilySearchEnvironment as F, NameForm as N, OAuthTokenResponse as O, PersonDisplay as P, Relationship as R, SDKLogger as S, FamilySearchSDKConfig as a, FamilySearchApiResponse as b, FamilySearchApiError as c, FamilySearchUser as d, FamilySearchPerson as e, PersonFact as f, PersonData as g, RelationshipDetails as h, PersonWithRelationships as i, PersonNotesResponse as j, PersonMemoriesResponse as k, PersonSearchResponse as l, PersonSourcesResponse as m, SourceDescription as n, SourceReference as o, FamilySearchPlace as p, PlaceDescription as q, PlaceSearchResult as r, PlaceSearchResponse as s, PlaceDetailsResponse as t, PedigreeData as u, EnhancedPerson as v, EnhancedPedigreeData as w, OAuthEndpoints as x, OAuthConfig as y, OAuthStateValidation as z };

package/dist/index.cjs

@@ -264,6 +264,37 @@ var FamilySearchSDK = class {
       return null;
     }
   }
+  /**
+   * Get sources for a person
+   * Fetches all source references linked to a person
+   *
+   * @param personId - FamilySearch person ID
+   * @returns Person sources response with source references and descriptions, or null if error
+   *
+   * @example
+   * ```typescript
+   * const sources = await sdk.getPersonSources('KWQS-BBQ');
+   * if (sources?.persons?.[0]?.sources) {
+   *   sources.persons[0].sources.forEach(source => {
+   *     console.log('Source:', source.descriptionId);
+   *   });
+   * }
+   * ```
+   */
+  async getPersonSources(personId) {
+    try {
+      const response = await this.get(
+        `/platform/tree/persons/${personId}/sources`
+      );
+      return response.data || null;
+    } catch (error) {
+      this.logger.error(
+        `[FamilySearch SDK] Failed to get sources for ${personId}:`,
+        error
+      );
+      return null;
+    }
+  }
   /**
    * Get couple relationship details
    */
@@ -1490,6 +1521,47 @@ function convertToGedcom(pedigreeData, options = {}) {
         }
       });
     }
+    if (person.sources?.persons?.[0]?.sources) {
+      const sourceDescMap = /* @__PURE__ */ new Map();
+      if (person.sources.sourceDescriptions && Array.isArray(person.sources.sourceDescriptions)) {
+        person.sources.sourceDescriptions.forEach((desc) => {
+          if (desc.id) {
+            sourceDescMap.set(desc.id, desc);
+          }
+        });
+      }
+      person.sources.persons[0].sources.forEach((sourceRef) => {
+        if (sourceRef.descriptionId) {
+          lines.push(`1 _FS_SOUR ${sourceRef.descriptionId}`);
+          const sourceDesc = sourceDescMap.get(sourceRef.descriptionId);
+          if (sourceDesc) {
+            if (sourceDesc.titles?.[0]?.value) {
+              lines.push(`2 TITL ${sourceDesc.titles[0].value}`);
+            }
+            if (sourceDesc.citations?.[0]?.value) {
+              lines.push(`2 TEXT ${sourceDesc.citations[0].value}`);
+            }
+            if (sourceDesc.about) {
+              const webUrl = transformSourceUrl(sourceDesc.about);
+              lines.push(`2 WWW ${webUrl}`);
+            }
+            if (sourceDesc.resourceType) {
+              lines.push(`2 NOTE Resource Type: ${sourceDesc.resourceType}`);
+            }
+          }
+          if (sourceRef.description) {
+            lines.push(`2 NOTE ${sourceRef.description}`);
+          }
+          if (sourceRef.qualifiers && Array.isArray(sourceRef.qualifiers)) {
+            sourceRef.qualifiers.forEach((qualifier) => {
+              if (qualifier.name && qualifier.value) {
+                lines.push(`2 NOTE ${qualifier.name}: ${qualifier.value}`);
+              }
+            });
+          }
+        }
+      });
+    }
   });
   let famIndex = 1;
   const familyIdMap = /* @__PURE__ */ new Map();