# DIDComm TypeScript/Javascript API

/**
 * Represents KeyAgreement record in DID Document
 */
interface DIDKeyAgreement {
    asJWK(): string; // public JWK
}

/**
 * Represents Authentication record in DID Document
 */
interface DIDKAuthentication {
    asJWK(): string; // public JWK
}

/**
 * Represents RouteKey record in DID Document
 */
interface DIDRouteKey {
    asJWK(): string; // public JWK
}

/**
 * Represents DID Document
 */
interface DIDDoc {
    keyAgreements(): [DIDKeyAgreement]; // [pubJWK]
    keyAgreement(kid: string): DIDKeyAgreement; // pubJWK
    authentications(): [DIDKAuthentication]; // [pubJWK]
    authentication(kid: string): DIDKAuthentication; // pubJWK
    routeKeys(): [DIDRouteKey];
}

/**
 * Represend DID Resolver concept.
 * Pluggubale implementation should allow resolve
 * DID Document for specific DID
 */
interface DIDResolver {
    resolve(did: string): Promise<DIDDoc>;
}

/**
 * Represents Secret for DID KeyAgreement
 */
interface DIDKeyAgreementSecret {
    asJWK(): string; // JWK
}

interface DIDKAuthenticationSecret {
    asJWK(): string; // JWK
}

interface DIDSecrets {
    keyAgreements(): [DIDKeyAgreementSecret];
    keyAgreement(kid: string): DIDKeyAgreementSecret;
    authentications(): [DIDKAuthenticationSecret];
    authentication(kid: string): DIDKAuthenticationSecret;
}

interface DIDSecretsResolver {
    resolve(did: string): Promise<DIDSecrets>;
}

// Message building, encryption and decryption helpers

class MessageBuilder {
    from(sender: string): MessageBuilder { return this; }

    to(recipients: string | string[]): MessageBuilder { return this; }

    typ(typ: string): MessageBuilder { return this; }

    created_at(created_at?: Date): MessageBuilder { return this; }

    expires_at(expires_at: Date): MessageBuilder { return this; }

    header(header: string, value: string | object): MessageBuilder { return this; }

    body(body: object): MessageBuilder { return this; }

    attach(aid: string, body: Uint8Array): MessageBuilder { return this; }

    finalize(): Message { return new Message(); }
}

// MessageTrustContext - contains trust infomration received after unpack
type MessageTrustContext = {
    from: string | undefined;
    to: [string];
    nonRepudable: boolean;
    // TODO: add more trust details
}

// MessageTrustOptions - defines consistency/trust checks for unpack
type MessageTrustOptions = {
    // TODO: add more trust details
}

// Common error for DIDComm
class DIDCommError {
    // TODO: add more trust details
}

/**
 * Wrapper for plain message. Provides 
 */
class Message {
    /**
     * New message building helper
     * @returns builder for new message
     */
    static build(): MessageBuilder { return new MessageBuilder(); }

    /**
     * 
     * @param raw raw message to unpack
     * @param options consistency checkign and trust options
     * @param didResolver didResolver to be used
     * @param secretsResolver secretsResolver to be used
     * @returns 
     * @throws DIDCommError
     */
    static unpack(
        raw: string,
        { options, didResolver, secretsResolver }: {
            options?: MessageTrustOptions; didResolver?: DIDResolver;
            secretsResolver?: DIDSecretsResolver;
        }): [Message, MessageTrustContext] {
        return [
            new Message(),
            { from: 'did:example:alice', to: ['did:example:bob'], nonRepudable: false }
        ];
    }

    from(): string { return "from"; }

    to(): [string] { return ["to"]; }

    created_at(): Date | undefined { return undefined; }

    expires_at(): Date | undefined { return undefined; }

    headers(): { [key: string]: object; } { return {}; }

    body(): object { return {}; }

    as_plain(): string { return "plain"; }

    async authcrypt({
        from, to, method, didResolver, secretsResolver }: {
            from?: string;
            to?: string | string[];
            method?: string;
            didResolver?: DIDResolver;
            secretsResolver?: DIDSecretsResolver;
        }): Promise<string> { return "authcrypt"; }

    async anoncrypt({
        to, method, didResolver, secretsResolver }: {
            to?: string | string[];
            method?: string;
            didResolver?: DIDResolver;
            secretsResolver?: DIDSecretsResolver;
        }): Promise<string> { return "anoncrypt"; }

    async anoncrypt_signed({
        from, to, method, didResolver, secretsResolver }: {
            from?: string;
            to?: string | string[];
            method?: string;
            didResolver?: DIDResolver;
            secretsResolver?: DIDSecretsResolver;
        }): Promise<string> { return "anoncrypt"; }

    async sign({
        from, method, secretsResolver }: {
            from?: string;
            method?: string;
            secretsResolver?: DIDSecretsResolver;
        }): Promise<string> { return "sign"; }
}

// - Examples

// Instanciate DIDResolver and DIDSecretsResolver instances

let didResolver = undefined as DIDResolver;
let secretsResolver = undefined as DIDSecretsResolver;

// Build message using builder. Note msg.as_plain() allow to get it as plain string.

let msg = Message
    .build()
    .from('did:example:alice')
    .to(['did:example:bob1', 'did:example:bob2'])
    .header('some-header', 'some-value')
    .header('more-header', 'more-value')
    .body({ 'say': 'hello' })
    .created_at()
    .expires_at(new Date())
    .finalize();

// Authcrypt message with default method and specific did and secrets resolvers
let authcrypted = msg.authcrypt({
    didResolver,
    secretsResolver,
});

// Custom method, from, to
let authcrypted1 = msg.authcrypt({
    method: 'ECDH-1PU+A256KW',
    didResolver,
    secretsResolver,
});

// Anocrypt message with default method and specific did and secrets resolvers
let anoncrypted = msg.anoncrypt({
    didResolver,
    secretsResolver,
});

// Anocrypt and sign message with default method and specific did and secrets resolvers
let anoncrypted_signed = msg.anoncrypt_signed({
    didResolver,
    secretsResolver,
});

// Sign message with default method and specific did and secrets resolvers
let signed = msg.sign({
    secretsResolver,
});

// Unpack received message with default trust options
let unpacked_msg = Message.unpack("...", {
    didResolver,
    secretsResolver
});