@documedis-components/prescription-sign/README.md

React component for signing electronic prescriptions with HIN authentication

# @documedis-components/prescription-sign

React component for signing electronic prescriptions with HIN authentication.

## Installation

```bash
npm install @documedis-components/prescription-sign
```

## Requirements

This component requires:

- React 18.0.0 or higher
- A running instance of the Documedis components-service backend

## Quick Start

```tsx
import { PrescriptionSign } from '@documedis-components/prescription-sign';

function App() {
  return (
    <PrescriptionSign
      environment="demo"
      accessToken="your-access-token"
      chmed="CHMED16A1..."
      onSuccess={(signedCHMED) => console.log('Signed:', signedCHMED)}
      onError={(error) => console.error('Error:', error)}
    />
  );
}
```

## API Reference

### PrescriptionSign Component

#### Props

| Parameter              | Type                                         | Required | Description                                                                                 |
| ---------------------- | -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `environment`          | `'demo'`                                     | ✅       | Environment configuration for the prescription service (currently only 'demo' is available) |
| `accessToken`          | `string`                                     | ✅       | Authentication token for backend service                                                    |
| `chmed`                | `string`                                     | ✅       | Encoded CHMED prescription data                                                             |
| `sessionToken`         | `string`                                     | ❌       | Optional existing session token to reuse authentication state                               |
| `onSessionTokenUpdate` | `(token: string) => void`                    | ❌       | Callback invoked when the session token is updated                                          |
| `onSuccess`            | `(signedCHMED: string) => void`              | ❌       | Callback invoked when prescription signing succeeds                                         |
| `onError`              | `(error: PrescriptionSignErrorType) => void` | ❌       | Callback invoked when prescription signing fails                                            |
| `logger`               | `PrescriptionSignLogger`                     | ❌       | Structured event emission for programmatic reaction and monitoring                          |
| `className`            | `string`                                     | ❌       | Additional CSS classes                                                                      |

### usePrescriptionSigning Hook

For advanced use cases, you can use the `usePrescriptionSigning` hook directly:

```tsx
import { usePrescriptionSigning } from '@documedis-components/prescription-sign';

function CustomSigningButton({ chmed, accessToken }) {
  const { start, interrupt, isActive, isSuccess, isError, signedCHMED } = usePrescriptionSigning({
    environment: 'demo',
    accessToken,
    onSuccess: (signedCHMED) => console.log('Signed!', signedCHMED),
    onError: (error) => console.error('Failed:', error),
  });

  if (isSuccess) {
    return <div>✅ Prescription signed</div>;
  }

  return (
    <button onClick={() => start(chmed)} disabled={isActive}>
      {isActive ? 'Signing...' : 'Sign Prescription'}
    </button>
  );
}
```

## Session Restoration

The library intelligently optimizes the signing process by checking session state first:

- **Fast Path**: When valid authentication data exists in session, the process can skip the authorization phase
- **Full Path**: When no valid session data exists, the full OAuth/SAML flow executes

## Error Types

- `canceled` - User canceled the signing process
- `popupClosed` - Authentication popup window was closed by user
- `popupBlocked` - Browser blocked the authentication popup window
- `login` - HIN authentication failed
- `chmed` - Invalid or malformed CHMED prescription data
- `oauth` - OAuth authentication with HIN failed
- `authCode` - Failed to obtain SAML authorization code
- `authHandle` - Failed to obtain SAML authentication handle
- `signature` - Failed to digitally sign the prescription

## Structured Logging

The component emits structured events for programmatic reaction:

```tsx
<PrescriptionSign
  environment="demo"
  accessToken="your-token"
  chmed="CHMED16A1..."
  logger={{
    emit: (event) => {
      // React to specific events
      if (event.type === 'flow_step_started' && event.step === 'oauth_flow_initiated') {
        showSpinner('Authenticating with HIN...');
      }

      if (event.type === 'error' && event.errorType === 'signature') {
        handleSignatureError(event.originalError);
      }
    },
  }}
/>
```

## Full Documentation

For complete documentation, examples, and interactive demos, visit:
[https://documentation.apps.documedis.ch](https://documentation.apps.documedis.ch)

## License

Copyright (c) 2025 Galenica AG. All rights reserved.

This software is proprietary and confidential. Unauthorized copying, modification, distribution, or use of this software, via any medium, is strictly prohibited without the express written permission of Galenica AG.

## Support

- Issues: Please contact your Documedis support representative