@welshare/sdk
    Preparing search index...

    Function submitDocumentReference

    • Submit a DocumentReference to Nillion storage.

      This function stores searchable metadata for binary files in Nillion, granting the builder read/execute access to the data. The DocumentReference links to a Binary resource via content.attachment.url using the format "binary/{id}".

      Parameters

      • keypair: SessionKeypair

        The user's session keypair for authentication

      • documentReference: {
            author?: {
                display?: string;
                id?: string;
                identifier?: { system?: string; value?: string };
                reference?: string;
                type?: string;
            }[];
            category?: {
                coding?: {
                    code?: string;
                    display?: string;
                    system: string;
                    userSelected?: boolean;
                    version?: string;
                }[];
                text?: string;
            }[];
            content: {
                attachment: {
                    contentType?: string;
                    creation?: string;
                    data?: string;
                    duration?: number;
                    frames?: number;
                    hash?: string;
                    height?: number;
                    id?: string;
                    language?: string;
                    pages?: number;
                    size?: number;
                    title?: string;
                    url?: string;
                    width?: number;
                };
                profile?: (
                    | {
                        valueCoding: {
                            code?: string;
                            display?: string;
                            system: string;
                            userSelected?: boolean;
                            version?: string;
                        };
                    }
                    | { valueUri: string }
                )[];
            }[];
            date?: string;
            description?: string;
            id: string;
            meta?: { lastUpdated?: string; profile?: string[]; versionId?: string };
            resourceType: "DocumentReference";
            securityLabel?: {
                coding?: {
                    code?: string;
                    display?: string;
                    system: string;
                    userSelected?: boolean;
                    version?: string;
                }[];
                text?: string;
            }[];
            status: string;
            subject?: {
                display?: string;
                id?: string;
                identifier?: { system?: string; value?: string };
                reference?: string;
                type?: string;
            };
            type?: {
                coding?: {
                    code?: string;
                    display?: string;
                    system: string;
                    userSelected?: boolean;
                    version?: string;
                }[];
                text?: string;
            };
        }

        The DocumentReference containing metadata about the binary file (type, category, description, subject, author, etc.)

        • Optionalauthor?: {
              display?: string;
              id?: string;
              identifier?: { system?: string; value?: string };
              reference?: string;
              type?: string;
          }[]

          Who and/or what authored the document

        • Optionalcategory?: {
              coding?: {
                  code?: string;
                  display?: string;
                  system: string;
                  userSelected?: boolean;
                  version?: string;
              }[];
              text?: string;
          }[]

          Categorization of document - use DOCUMENT_CATEGORY_CONCEPTS

        • content: {
              attachment: {
                  contentType?: string;
                  creation?: string;
                  data?: string;
                  duration?: number;
                  frames?: number;
                  hash?: string;
                  height?: number;
                  id?: string;
                  language?: string;
                  pages?: number;
                  size?: number;
                  title?: string;
                  url?: string;
                  width?: number;
              };
              profile?: (
                  | {
                      valueCoding: {
                          code?: string;
                          display?: string;
                          system: string;
                          userSelected?: boolean;
                          version?: string;
                      };
                  }
                  | { valueUri: string }
              )[];
          }[]

          Document content - array of content elements. Each element has an attachment that references the Binary resource via url (e.g., "binary/{id}") and includes metadata like contentType, size, title.

        • Optionaldate?: string

          When this document reference was created

        • Optionaldescription?: string

          Human-readable description (title/summary)

        • id: string
        • Optionalmeta?: { lastUpdated?: string; profile?: string[]; versionId?: string }
        • resourceType: "DocumentReference"
        • OptionalsecurityLabel?: {
              coding?: {
                  code?: string;
                  display?: string;
                  system: string;
                  userSelected?: boolean;
                  version?: string;
              }[];
              text?: string;
          }[]

          Document security labels

        • status: string

          Document status: current | superseded | entered-in-error

        • Optionalsubject?: {
              display?: string;
              id?: string;
              identifier?: { system?: string; value?: string };
              reference?: string;
              type?: string;
          }

          Who/what is the subject of the document (typically patient reference)

        • Optionaltype?: {
              coding?: {
                  code?: string;
                  display?: string;
                  system: string;
                  userSelected?: boolean;
                  version?: string;
              }[];
              text?: string;
          }

          Kind of document (LOINC code) - use DOCUMENT_TYPE_CONCEPTS

      • environment: WelshareApiEnvironment | "production" | "staging" | "preview" | "development"

        The Welshare API environment (name or config object)

      Returns Promise<{ insertedUid: string }>

      Promise containing insertedUid (the Nillion document ID)

      Error if the submission fails or no document ID is returned

      import {
        WelshareApi,
        Keypair,
        DocumentReferenceHelpers,
        DOCUMENT_TYPE_CONCEPTS,
      } from "@welshare/sdk";

      // After uploading a binary file
      const docRef = DocumentReferenceHelpers.createDocumentReference({
        binaryId: binaryUploadResult.insertedUid,
        fileName: file.name,
        fileType: file.type,
        fileSize: file.size,
        subjectDid: Keypair.keypairKeyDid(keypair).didString, //Nillion 2.0 requires did:key as a method
        description: "My document",
        type: DOCUMENT_TYPE_CONCEPTS.PHOTO_DOCUMENT,
      });

      const { insertedUid } = await WelshareApi.submitDocumentReference(
        keypair,
        docRef,
        "production"
      );

      Side effects:

      • Calls fetchDelegation() to obtain a NUC delegation from the Welshare API
      • Creates a new document in the Nillion DocumentReference collection
      • Grants the environment's builder DID read/execute access to the document

      The DocumentReference is linked to a Binary resource but does not contain any secret data itself - the encryption key remains in the Binary record.

    Settings

    Member Visibility