@ondewo/sip-client-nodejs 5.4.1 → 5.5.0

package/README.md

@@ -70,3 +70,97 @@ npm
 └── README.md
 ```
 
+## TLS, mutual TLS and certificates
+
+gRPC encrypts with **TLS** ("SSL" in names such as `credentials.createSsl` or `grpc.ssl_target_name_override` is legacy naming). The package ships a channel helper, `auth/grpcChannel` (exported from the package root), that builds the `@grpc/grpc-js` credentials and channel options for every generated client:
+
+| Mode                                    | `useSecureChannel` | Config fields                                                   |
+|-----------------------------------------|--------------------|-----------------------------------------------------------------|
+| Plaintext (not for production)          | `false`            | none                                                            |
+| TLS, server verified by the trust store | `true` (default)   | none                                                            |
+| TLS, server verified by your CA         | `true` (default)   | `grpcCert` = PEM of the CA that signed the server certificate   |
+| Mutual TLS                              | `true` (default)   | `grpcCert` (optional) plus `grpcClientCert` and `grpcClientKey` |
+
+Rules the code enforces:
+
+- The three fields hold **PEM content** (`string` or `Buffer`), **not file paths**. Read the files yourself; a value without a PEM header line is refused.
+- `grpcClientCert` and `grpcClientKey` go together: setting only one throws when the `GrpcClientConfig` is built, and `createChannelCredentials` refuses half a pair again before anything reaches gRPC. Empty strings on both mean plain server-authenticated TLS.
+- `useSecureChannel: false` with a client certificate throws instead of silently dropping the identity. A plaintext channel otherwise logs a warning naming `host:port` (through `console.warn`, or the `logger` you pass).
+- Without `grpcCert` the server is verified against Node's default CA store (Node's bundled Mozilla roots plus `NODE_EXTRA_CA_CERTS`; start Node with `--use-system-ca` to use the operating system's store instead).
+- The host you connect to must match a subject alternative name (SAN) of the server certificate. When you connect by IP and the certificate has no IP SAN, pass the name to check as the channel option `'grpc.ssl_target_name_override'`.
+- A bare IPv6 host is bracketed for you (`::1` becomes `[::1]:50051`).
+
+```ts
+import { readFileSync } from 'fs';
+
+import * as grpc from '@grpc/grpc-js';
+import { createChannelCredentials, createGrpcClient, GrpcClientConfig, SipClient } from '@ondewo/sip-client-nodejs';
+
+const config = new GrpcClientConfig({
+  host: '10.0.0.5',
+  port: 50051,
+  grpcCert: readFileSync('certs/ca.pem'),
+  grpcClientCert: readFileSync('certs/client.pem'), // leave both out for server-authenticated TLS
+  grpcClientKey: readFileSync('certs/client.key')
+});
+
+const client: SipClient = createGrpcClient(SipClient, config, {
+  channelOptions: { 'grpc.ssl_target_name_override': 'sip.example.internal' } // only when connecting by IP
+});
+```
+
+`createGrpcClient` starts from `DEFAULT_GRPC_CHANNEL_OPTIONS` (maximum message size 2³¹-1 bytes in both directions, reconnect backoff capped at 5 s) and applies your `channelOptions` on top. To build credentials only, call `createChannelCredentials(config, { useSecureChannel })` and pass the result to any generated client constructor.
+
+**One connection for several services.** Clients built with the **same credentials object** (and the same target and options) share one connection, so the TLS handshake happens once:
+
+```ts
+const credentials: grpc.ChannelCredentials = createChannelCredentials(config);
+const first = createGrpcClient(SipClient, config, { credentials });
+const second = createGrpcClient(SipClient, config, { credentials }); // any other generated client works the same way
+```
+
+**Keepalive is off by default.** `@grpc/grpc-js` has no `grpc.http2.max_pings_without_data`, so with `grpc.keepalive_time_ms` set it keeps pinging a stream that carries no data, and a grpc-core server (as every ONDEWO server is) answers with `GOAWAY too_many_pings`: the call fails with `RESOURCE_EXHAUSTED` (measured: after 150 s at a 30 s keepalive). The Python SDKs' 30 s keepalive therefore is not copied; set `grpc.keepalive_time_ms` yourself only against a server whose `grpc.http2.min_ping_interval_without_data_ms` allows it. `grpc.keepalive_timeout_ms` is preset to 20 s for that case.
+
+### A test PKI with openssl
+
+A CA, a server certificate with SANs and a client certificate with the `clientAuth` extended key usage. For tests only: the keys are unencrypted.
+
+```bash
+openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes -days 365 \
+  -subj "/CN=Test CA" -keyout ca.key -out ca.pem
+
+printf 'subjectAltName=DNS:localhost,IP:127.0.0.1\nextendedKeyUsage=serverAuth\n' > server.ext
+openssl req -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \
+  -subj "/CN=localhost" -keyout server.key -out server.csr
+openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -CAcreateserial -days 365 \
+  -extfile server.ext -out server.pem
+
+printf 'extendedKeyUsage=clientAuth\n' > client.ext
+openssl req -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \
+  -subj "/CN=my-client" -keyout client.key -out client.csr
+openssl x509 -req -in client.csr -CA ca.pem -CAkey ca.key -CAcreateserial -days 365 \
+  -extfile client.ext -out client.pem
+
+chmod 600 *.key
+openssl verify -CAfile ca.pem server.pem client.pem
+```
+
+The client then uses `ca.pem` / `client.pem` / `client.key`; a server that requires client certificates uses `server.pem` / `server.key` and trusts `ca.pem` for its clients.
+
+### TLS security notes
+
+- Keep the client key out of source control and out of serialized configs: load it from a file (mode `0600`) or a secret store at startup.
+- `GrpcClientConfig` renders the key as `***REDACTED***` in `toString()`, `util.inspect()` / `console.log()` and `JSON.stringify()` (an empty key renders empty). There is no serializer that writes the key, so a config cannot be persisted with it. A plain object you pass instead of a `GrpcClientConfig` has none of this protection: do not log it.
+- No error message of the helper contains a PEM, a key or a whole config; they name the field and `host:port`.
+
+### TLS troubleshooting
+
+A failed handshake surfaces as gRPC status `UNAVAILABLE` (14); the cause is in the error's `details`:
+
+- **`unable to verify the first certificate`**: the server certificate is not signed by `grpcCert` (or, without `grpcCert`, not by a CA Node trusts). Pass the CA that signed the server certificate.
+- **`ERR_TLS_CERT_ALTNAME_INVALID: Hostname/IP does not match certificate's altnames`**: the host you dial is not a SAN of the server certificate. Dial a name in the certificate, or set `'grpc.ssl_target_name_override'`. Some Node releases (seen on 22.23 and 24.18) also reject an IPv6 literal against a matching IP SAN; the override to a DNS SAN works around it.
+- **`tlsv13 alert certificate required`**: the server requires mutual TLS and the client sent no certificate. Set `grpcClientCert` and `grpcClientKey`.
+- **`Failed to connect`** right after the handshake with a client certificate: the server does not trust the CA that signed `grpcClientCert`.
+- **`... grpcCert is not PEM content (no PEM header line)`** (thrown when the config is built): a field holds a file path or other text instead of the file's content. Pass `readFileSync(path)`.
+- **`createChannelCredentials for host:port: gRPC rejected the TLS material: ... key values mismatch`** (thrown, not a call error): `grpcClientKey` is not the key of `grpcClientCert`. Other OpenSSL reasons there mean a damaged PEM block.
+

package/api/ondewo/sip/sip_grpc_pb.d.ts

@@ -21,6 +21,9 @@ interface ISipService extends grpc.ServiceDefinition<grpc.UntypedServiceImplemen
     sipPlayWavFiles: ISipService_ISipPlayWavFiles;
     sipMute: ISipService_ISipMute;
     sipUnMute: ISipService_ISipUnMute;
+    sipReportAnsweringMachineDetected: ISipService_ISipReportAnsweringMachineDetected;
+    sipSetCallMediaControl: ISipService_ISipSetCallMediaControl;
+    sipStreamCallAudio: ISipService_ISipStreamCallAudio;
 }
 
 interface ISipService_ISipStartSession extends grpc.MethodDefinition<ondewo_sip_sip_pb.SipStartSessionRequest, ondewo_sip_sip_pb.SipStatus> {
@@ -122,6 +125,33 @@ interface ISipService_ISipUnMute extends grpc.MethodDefinition<google_protobuf_e
     responseSerialize: grpc.serialize<ondewo_sip_sip_pb.SipStatus>;
     responseDeserialize: grpc.deserialize<ondewo_sip_sip_pb.SipStatus>;
 }
+interface ISipService_ISipReportAnsweringMachineDetected extends grpc.MethodDefinition<ondewo_sip_sip_pb.SipReportAnsweringMachineDetectedRequest, ondewo_sip_sip_pb.SipStatus> {
+    path: "/ondewo.sip.Sip/SipReportAnsweringMachineDetected";
+    requestStream: false;
+    responseStream: false;
+    requestSerialize: grpc.serialize<ondewo_sip_sip_pb.SipReportAnsweringMachineDetectedRequest>;
+    requestDeserialize: grpc.deserialize<ondewo_sip_sip_pb.SipReportAnsweringMachineDetectedRequest>;
+    responseSerialize: grpc.serialize<ondewo_sip_sip_pb.SipStatus>;
+    responseDeserialize: grpc.deserialize<ondewo_sip_sip_pb.SipStatus>;
+}
+interface ISipService_ISipSetCallMediaControl extends grpc.MethodDefinition<ondewo_sip_sip_pb.SipSetCallMediaControlRequest, ondewo_sip_sip_pb.SipStatus> {
+    path: "/ondewo.sip.Sip/SipSetCallMediaControl";
+    requestStream: false;
+    responseStream: false;
+    requestSerialize: grpc.serialize<ondewo_sip_sip_pb.SipSetCallMediaControlRequest>;
+    requestDeserialize: grpc.deserialize<ondewo_sip_sip_pb.SipSetCallMediaControlRequest>;
+    responseSerialize: grpc.serialize<ondewo_sip_sip_pb.SipStatus>;
+    responseDeserialize: grpc.deserialize<ondewo_sip_sip_pb.SipStatus>;
+}
+interface ISipService_ISipStreamCallAudio extends grpc.MethodDefinition<ondewo_sip_sip_pb.SipCallAudioRequest, ondewo_sip_sip_pb.SipCallAudioResponse> {
+    path: "/ondewo.sip.Sip/SipStreamCallAudio";
+    requestStream: true;
+    responseStream: true;
+    requestSerialize: grpc.serialize<ondewo_sip_sip_pb.SipCallAudioRequest>;
+    requestDeserialize: grpc.deserialize<ondewo_sip_sip_pb.SipCallAudioRequest>;
+    responseSerialize: grpc.serialize<ondewo_sip_sip_pb.SipCallAudioResponse>;
+    responseDeserialize: grpc.deserialize<ondewo_sip_sip_pb.SipCallAudioResponse>;
+}
 
 export const SipService: ISipService;
 
@@ -137,6 +167,9 @@ export interface ISipServer {
     sipPlayWavFiles: grpc.handleUnaryCall<ondewo_sip_sip_pb.SipPlayWavFilesRequest, ondewo_sip_sip_pb.SipStatus>;
     sipMute: grpc.handleUnaryCall<google_protobuf_empty_pb.Empty, ondewo_sip_sip_pb.SipStatus>;
     sipUnMute: grpc.handleUnaryCall<google_protobuf_empty_pb.Empty, ondewo_sip_sip_pb.SipStatus>;
+    sipReportAnsweringMachineDetected: grpc.handleUnaryCall<ondewo_sip_sip_pb.SipReportAnsweringMachineDetectedRequest, ondewo_sip_sip_pb.SipStatus>;
+    sipSetCallMediaControl: grpc.handleUnaryCall<ondewo_sip_sip_pb.SipSetCallMediaControlRequest, ondewo_sip_sip_pb.SipStatus>;
+    sipStreamCallAudio: grpc.handleBidiStreamingCall<ondewo_sip_sip_pb.SipCallAudioRequest, ondewo_sip_sip_pb.SipCallAudioResponse>;
 }
 
 export interface ISipClient {
@@ -173,6 +206,15 @@ export interface ISipClient {
     sipUnMute(request: google_protobuf_empty_pb.Empty, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
     sipUnMute(request: google_protobuf_empty_pb.Empty, metadata: grpc.Metadata, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
     sipUnMute(request: google_protobuf_empty_pb.Empty, metadata: grpc.Metadata, options: Partial<grpc.CallOptions>, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
+    sipReportAnsweringMachineDetected(request: ondewo_sip_sip_pb.SipReportAnsweringMachineDetectedRequest, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
+    sipReportAnsweringMachineDetected(request: ondewo_sip_sip_pb.SipReportAnsweringMachineDetectedRequest, metadata: grpc.Metadata, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
+    sipReportAnsweringMachineDetected(request: ondewo_sip_sip_pb.SipReportAnsweringMachineDetectedRequest, metadata: grpc.Metadata, options: Partial<grpc.CallOptions>, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
+    sipSetCallMediaControl(request: ondewo_sip_sip_pb.SipSetCallMediaControlRequest, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
+    sipSetCallMediaControl(request: ondewo_sip_sip_pb.SipSetCallMediaControlRequest, metadata: grpc.Metadata, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
+    sipSetCallMediaControl(request: ondewo_sip_sip_pb.SipSetCallMediaControlRequest, metadata: grpc.Metadata, options: Partial<grpc.CallOptions>, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
+    sipStreamCallAudio(): grpc.ClientDuplexStream<ondewo_sip_sip_pb.SipCallAudioRequest, ondewo_sip_sip_pb.SipCallAudioResponse>;
+    sipStreamCallAudio(options: Partial<grpc.CallOptions>): grpc.ClientDuplexStream<ondewo_sip_sip_pb.SipCallAudioRequest, ondewo_sip_sip_pb.SipCallAudioResponse>;
+    sipStreamCallAudio(metadata: grpc.Metadata, options?: Partial<grpc.CallOptions>): grpc.ClientDuplexStream<ondewo_sip_sip_pb.SipCallAudioRequest, ondewo_sip_sip_pb.SipCallAudioResponse>;
 }
 
 export class SipClient extends grpc.Client implements ISipClient {
@@ -210,4 +252,12 @@ export class SipClient extends grpc.Client implements ISipClient {
     public sipUnMute(request: google_protobuf_empty_pb.Empty, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
     public sipUnMute(request: google_protobuf_empty_pb.Empty, metadata: grpc.Metadata, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
     public sipUnMute(request: google_protobuf_empty_pb.Empty, metadata: grpc.Metadata, options: Partial<grpc.CallOptions>, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
+    public sipReportAnsweringMachineDetected(request: ondewo_sip_sip_pb.SipReportAnsweringMachineDetectedRequest, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
+    public sipReportAnsweringMachineDetected(request: ondewo_sip_sip_pb.SipReportAnsweringMachineDetectedRequest, metadata: grpc.Metadata, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
+    public sipReportAnsweringMachineDetected(request: ondewo_sip_sip_pb.SipReportAnsweringMachineDetectedRequest, metadata: grpc.Metadata, options: Partial<grpc.CallOptions>, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
+    public sipSetCallMediaControl(request: ondewo_sip_sip_pb.SipSetCallMediaControlRequest, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
+    public sipSetCallMediaControl(request: ondewo_sip_sip_pb.SipSetCallMediaControlRequest, metadata: grpc.Metadata, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
+    public sipSetCallMediaControl(request: ondewo_sip_sip_pb.SipSetCallMediaControlRequest, metadata: grpc.Metadata, options: Partial<grpc.CallOptions>, callback: (error: grpc.ServiceError | null, response: ondewo_sip_sip_pb.SipStatus) => void): grpc.ClientUnaryCall;
+    public sipStreamCallAudio(options?: Partial<grpc.CallOptions>): grpc.ClientDuplexStream<ondewo_sip_sip_pb.SipCallAudioRequest, ondewo_sip_sip_pb.SipCallAudioResponse>;
+    public sipStreamCallAudio(metadata?: grpc.Metadata, options?: Partial<grpc.CallOptions>): grpc.ClientDuplexStream<ondewo_sip_sip_pb.SipCallAudioRequest, ondewo_sip_sip_pb.SipCallAudioResponse>;
 }

package/api/ondewo/sip/sip_grpc_pb.js

@@ -32,6 +32,28 @@ function deserialize_google_protobuf_Empty(buffer_arg) {
   return google_protobuf_empty_pb.Empty.deserializeBinary(new Uint8Array(buffer_arg));
 }
 
+function serialize_ondewo_sip_SipCallAudioRequest(arg) {
+  if (!(arg instanceof ondewo_sip_sip_pb.SipCallAudioRequest)) {
+    throw new Error('Expected argument of type ondewo.sip.SipCallAudioRequest');
+  }
+  return Buffer.from(arg.serializeBinary());
+}
+
+function deserialize_ondewo_sip_SipCallAudioRequest(buffer_arg) {
+  return ondewo_sip_sip_pb.SipCallAudioRequest.deserializeBinary(new Uint8Array(buffer_arg));
+}
+
+function serialize_ondewo_sip_SipCallAudioResponse(arg) {
+  if (!(arg instanceof ondewo_sip_sip_pb.SipCallAudioResponse)) {
+    throw new Error('Expected argument of type ondewo.sip.SipCallAudioResponse');
+  }
+  return Buffer.from(arg.serializeBinary());
+}
+
+function deserialize_ondewo_sip_SipCallAudioResponse(buffer_arg) {
+  return ondewo_sip_sip_pb.SipCallAudioResponse.deserializeBinary(new Uint8Array(buffer_arg));
+}
+
 function serialize_ondewo_sip_SipEndCallRequest(arg) {
   if (!(arg instanceof ondewo_sip_sip_pb.SipEndCallRequest)) {
     throw new Error('Expected argument of type ondewo.sip.SipEndCallRequest');
@@ -65,6 +87,28 @@ function deserialize_ondewo_sip_SipRegisterAccountRequest(buffer_arg) {
   return ondewo_sip_sip_pb.SipRegisterAccountRequest.deserializeBinary(new Uint8Array(buffer_arg));
 }
 
+function serialize_ondewo_sip_SipReportAnsweringMachineDetectedRequest(arg) {
+  if (!(arg instanceof ondewo_sip_sip_pb.SipReportAnsweringMachineDetectedRequest)) {
+    throw new Error('Expected argument of type ondewo.sip.SipReportAnsweringMachineDetectedRequest');
+  }
+  return Buffer.from(arg.serializeBinary());
+}
+
+function deserialize_ondewo_sip_SipReportAnsweringMachineDetectedRequest(buffer_arg) {
+  return ondewo_sip_sip_pb.SipReportAnsweringMachineDetectedRequest.deserializeBinary(new Uint8Array(buffer_arg));
+}
+
+function serialize_ondewo_sip_SipSetCallMediaControlRequest(arg) {
+  if (!(arg instanceof ondewo_sip_sip_pb.SipSetCallMediaControlRequest)) {
+    throw new Error('Expected argument of type ondewo.sip.SipSetCallMediaControlRequest');
+  }
+  return Buffer.from(arg.serializeBinary());
+}
+
+function deserialize_ondewo_sip_SipSetCallMediaControlRequest(buffer_arg) {
+  return ondewo_sip_sip_pb.SipSetCallMediaControlRequest.deserializeBinary(new Uint8Array(buffer_arg));
+}
+
 function serialize_ondewo_sip_SipStartCallRequest(arg) {
   if (!(arg instanceof ondewo_sip_sip_pb.SipStartCallRequest)) {
     throw new Error('Expected argument of type ondewo.sip.SipStartCallRequest');
@@ -135,7 +179,8 @@ sipStartSession: {
     responseSerialize: serialize_ondewo_sip_SipStatus,
     responseDeserialize: deserialize_ondewo_sip_SipStatus,
   },
-  // <p>Ends a SIP session for an account registered at a SIP server</p>
+  // Not idempotent (no idempotency_level): (re)creates the SIP session and registration.
+// <p>Ends a SIP session for an account registered at a SIP server</p>
 sipEndSession: {
     path: '/ondewo.sip.Sip/SipEndSession',
     requestStream: false,
@@ -147,7 +192,8 @@ sipEndSession: {
     responseSerialize: serialize_ondewo_sip_SipStatus,
     responseDeserialize: deserialize_ondewo_sip_SipStatus,
   },
-  // <p>Starts a call in an active SIP session for an account registered at a SIP server</p>
+  // Not idempotent (no idempotency_level): tears down the session; a repeat records a new status.
+// <p>Starts a call in an active SIP session for an account registered at a SIP server</p>
 sipStartCall: {
     path: '/ondewo.sip.Sip/SipStartCall',
     requestStream: false,
@@ -159,7 +205,8 @@ sipStartCall: {
     responseSerialize: serialize_ondewo_sip_SipStatus,
     responseDeserialize: deserialize_ondewo_sip_SipStatus,
   },
-  // <p>Ends a call in an active SIP session for an account registered at a SIP server</p>
+  // Not idempotent (no idempotency_level): a repeat dials a second call.
+// <p>Ends a call in an active SIP session for an account registered at a SIP server</p>
 sipEndCall: {
     path: '/ondewo.sip.Sip/SipEndCall',
     requestStream: false,
@@ -171,7 +218,20 @@ sipEndCall: {
     responseSerialize: serialize_ondewo_sip_SipStatus,
     responseDeserialize: deserialize_ondewo_sip_SipStatus,
   },
-  // <p>Transfers a call in an active SIP session for an account registered at a SIP server to another SIP account or phone number specified by <code>transfer_id</code></p>
+  // Not idempotent (no idempotency_level): a repeat without a call appends its refusal to the history and ends
+// a one-shot caller container; unscoped it can end the next call.
+// <p>Transfers a call in an active SIP session for an account registered at a SIP server to another SIP account or phone number specified by <code>transfer_id</code></p>
+// <p>Call scoping: when the gRPC metadatum <code>x-ondewo-expected-call-id</code> is present it must equal
+// <code>SipStatus.call_id</code> of the ongoing call, otherwise the request is refused with
+// <code>exception_name=CallScopeMismatch</code> and nothing is assigned to the status. When it is absent the request is
+// accepted for backward compatibility (unless the server requires call scoping).</p>
+// <p>With <code>outcome_timeout_ms = 0</code> the call is transferred as before (REFER, then an immediate hangup).
+// With <code>outcome_timeout_ms &gt; 0</code> see <code>SipTransferCallRequest.outcome_timeout_ms</code>.</p>
+// <p>Refused while invited participants are present (see
+// <code>SipSetCallMediaControlRequest.participants_present</code>): a REFER into a conference bridge transfers every
+// party in it, the invited participant included. The refusal is RETURNED as <code>TRANSFER_CALL_FAILED</code> with
+// <code>exception_name=ParticipantsPresent</code> and <code>description = reason=participants-present</code>; nothing
+// is sent and the call is kept.</p>
 sipTransferCall: {
     path: '/ondewo.sip.Sip/SipTransferCall',
     requestStream: false,
@@ -183,7 +243,8 @@ sipTransferCall: {
     responseSerialize: serialize_ondewo_sip_SipStatus,
     responseDeserialize: deserialize_ondewo_sip_SipStatus,
   },
-  // <p>Registers s SIP account at a SIP server</p>
+  // Not idempotent (no idempotency_level): a repeat sends another REFER.
+// <p>Registers s SIP account at a SIP server</p>
 sipRegisterAccount: {
     path: '/ondewo.sip.Sip/SipRegisterAccount',
     requestStream: false,
@@ -195,7 +256,8 @@ sipRegisterAccount: {
     responseSerialize: serialize_ondewo_sip_SipStatus,
     responseDeserialize: deserialize_ondewo_sip_SipStatus,
   },
-  // <p>Gets the current SIP status</p>
+  // Not idempotent (no idempotency_level): re-registers the account at the SIP server.
+// <p>Gets the current SIP status</p>
 sipGetSipStatus: {
     path: '/ondewo.sip.Sip/SipGetSipStatus',
     requestStream: false,
@@ -220,6 +282,8 @@ sipGetSipStatusHistory: {
     responseDeserialize: deserialize_ondewo_sip_SipStatusHistoryResponse,
   },
   // <p>Plays wav files during an ongoing call of an active SIP session</p>
+// <p>Call scoping as for <code>SipTransferCall</code>: a present <code>x-ondewo-expected-call-id</code> metadatum must
+// match <code>SipStatus.call_id</code>.</p>
 sipPlayWavFiles: {
     path: '/ondewo.sip.Sip/SipPlayWavFiles',
     requestStream: false,
@@ -231,7 +295,11 @@ sipPlayWavFiles: {
     responseSerialize: serialize_ondewo_sip_SipStatus,
     responseDeserialize: deserialize_ondewo_sip_SipStatus,
   },
-  // <p>Mutes the microphone in an ongoing call of an active SIP session</p>
+  // Not idempotent (no idempotency_level): a repeat plays the files again.
+// <p>Mutes the microphone in an ongoing call of an active SIP session</p>
+// <p>Call scoping as for <code>SipTransferCall</code>. Sent by the in-container speech-to-speech pipeline it mutes only
+// the bot's own mixer slot; sent by a remote client it sets the operator mute of
+// <code>SipSetCallMediaControl</code>, which the pipeline cannot undo.</p>
 sipMute: {
     path: '/ondewo.sip.Sip/SipMute',
     requestStream: false,
@@ -243,7 +311,9 @@ sipMute: {
     responseSerialize: serialize_ondewo_sip_SipStatus,
     responseDeserialize: deserialize_ondewo_sip_SipStatus,
   },
-  // <p>Un-mutes the microphone in an ongoing call of an active SIP session</p>
+  // Not idempotent (no idempotency_level): without a call it assigns NO_ONGOING_CALL and appends to the history.
+// <p>Un-mutes the microphone in an ongoing call of an active SIP session</p>
+// <p>Call scoping and the split between the pipeline's own mute and the operator mute as for <code>SipMute</code>.</p>
 sipUnMute: {
     path: '/ondewo.sip.Sip/SipUnMute',
     requestStream: false,
@@ -255,6 +325,71 @@ sipUnMute: {
     responseSerialize: serialize_ondewo_sip_SipStatus,
     responseDeserialize: deserialize_ondewo_sip_SipStatus,
   },
+  // Not idempotent (no idempotency_level): without a call it assigns NO_ONGOING_CALL and appends to the history.
+// <p>Reports that answering machine detection reached a verdict on the ongoing outgoing call. Sets the status
+// <code>OUTGOING_CALL_ANSWERING_MACHINE_DETECTED</code> carrying <code>amd_result</code>; the call stays up.</p>
+// <p>Called by the speech-to-speech pipeline (ONDEWO-CSI) inside the same container, i.e. over loopback only.
+// Refused, and the current status left untouched, when no outgoing call is connected: the returned
+// <code>SipStatus</code> then carries the refusal in <code>exception_name</code> and <code>description</code></p>
+sipReportAnsweringMachineDetected: {
+    path: '/ondewo.sip.Sip/SipReportAnsweringMachineDetected',
+    requestStream: false,
+    responseStream: false,
+    requestType: ondewo_sip_sip_pb.SipReportAnsweringMachineDetectedRequest,
+    responseType: ondewo_sip_sip_pb.SipStatus,
+    requestSerialize: serialize_ondewo_sip_SipReportAnsweringMachineDetectedRequest,
+    requestDeserialize: deserialize_ondewo_sip_SipReportAnsweringMachineDetectedRequest,
+    responseSerialize: serialize_ondewo_sip_SipStatus,
+    responseDeserialize: deserialize_ondewo_sip_SipStatus,
+  },
+  // Not idempotent (no idempotency_level): assigns a status and records answering machine detection telemetry.
+// <p>Call-scoped operator media control of the ongoing call: mute the bot and/or pause its listening.</p>
+// <p>Metadata REQUIRED: <code>x-ondewo-expected-call-id</code> (must equal <code>SipStatus.call_id</code> of the ongoing
+// call) and <code>x-ondewo-sip-call-control-token</code> (the per-container call-control token).</p>
+// <p>Every request sets a desired level per owner and never toggles; a repeat leaves the level unchanged. The bot is
+// muted while ANY owner holds a mute, and its listening is paused while ANY owner holds a pause.</p>
+// <p>Returns the live status with <code>call_id</code>, <code>bot_muted</code>, <code>listening_paused</code> and
+// <code>call_audio_streams</code> filled. Refusals are RETURNED in <code>exception_name</code> /
+// <code>description</code> (<code>CallScopeMismatch</code>, <code>CallControlUnauthenticated</code>,
+// <code>NoOngoingCall</code>, <code>AmdInProgress</code>, <code>CsiMediaControlFailed</code>) and never assigned to
+// the shared status. When the pipeline refuses or fails, a requested pause is rolled back and a requested mute is
+// kept (the safe direction); the returned fields carry the actual level.</p>
+sipSetCallMediaControl: {
+    path: '/ondewo.sip.Sip/SipSetCallMediaControl',
+    requestStream: false,
+    responseStream: false,
+    requestType: ondewo_sip_sip_pb.SipSetCallMediaControlRequest,
+    responseType: ondewo_sip_sip_pb.SipStatus,
+    requestSerialize: serialize_ondewo_sip_SipSetCallMediaControlRequest,
+    requestDeserialize: deserialize_ondewo_sip_SipSetCallMediaControlRequest,
+    responseSerialize: serialize_ondewo_sip_SipStatus,
+    responseDeserialize: deserialize_ondewo_sip_SipStatus,
+  },
+  // Deliberately unmarked although a repeat leaves the level unchanged: a retried attempt can land after a newer
+// request of the same owner and restore a stale mute or pause.
+// <p>Bidirectional live audio of the ongoing call.</p>
+// <p>The first request MUST be <code>config</code> and must arrive within 2 seconds. Metadata as for
+// <code>SipSetCallMediaControl</code>.</p>
+// <p>LISTEN receives the caller (plus any conference participants) mixed with the bot. TALK sends the agent's audio to
+// the caller; it REQUIRES <code>take_over</code>, i.e. the bot is muted and does not listen while the stream is
+// connected, and in TALK the agent hears the caller only. Audio is LINEAR16 little-endian mono in 20 ms frames.</p>
+// <p>gRPC status codes: <code>UNAUTHENTICATED</code> (token), <code>FAILED_PRECONDITION</code> (call id mismatch, no
+// connected call, answering machine detection in progress, bot still speaking at TALK start),
+// <code>INVALID_ARGUMENT</code> (missing or invalid <code>config</code>, wrong frame size),
+// <code>RESOURCE_EXHAUSTED</code> (stream cap reached, a second TALK). A normal end sends one <code>ended</code>
+// message and then OK.</p>
+sipStreamCallAudio: {
+    path: '/ondewo.sip.Sip/SipStreamCallAudio',
+    requestStream: true,
+    responseStream: true,
+    requestType: ondewo_sip_sip_pb.SipCallAudioRequest,
+    responseType: ondewo_sip_sip_pb.SipCallAudioResponse,
+    requestSerialize: serialize_ondewo_sip_SipCallAudioRequest,
+    requestDeserialize: deserialize_ondewo_sip_SipCallAudioRequest,
+    responseSerialize: serialize_ondewo_sip_SipCallAudioResponse,
+    responseDeserialize: deserialize_ondewo_sip_SipCallAudioResponse,
+  },
+  // Not idempotent (no idempotency_level): a stream takes a slot and, in TALK, takes over the call.
 };
 
 exports.SipClient = grpc.makeGenericClientConstructor(SipService, 'Sip');