Update docs

.python-version

@@ -0,0 +1 @@
+3.10

.rtx.toml

@@ -0,0 +1,3 @@
+[tools]
+node = "16"
+python = "3.10"

README.md

@@ -3,13 +3,33 @@
 This is the project for WGTwo API docs v0, hosted at [v0.docs.wgtwo.com/](https://v0.docs.wgtwo.com/).
 
 Prior to 2023-03-29 these docs were hosted on docs.wgtwo.com.
+The actual docs.wgtwo.com code can be found in loltel/public-api-docs.
 
 ## Contributing
 Check out [CONTRIBUTING.md](CONTRIBUTING.md) and add your content to [docs/](docs/)
 
+## Prerequisites / install
+- Node.js 16.x
+- vips (for image processing) `brew install vips` (for any arm/Mac M1+ users)
+- python 3.10
+
+If you use pyenv and rtx/asdf then this might be enough:
+
+```shell
+brew install vips
+npm install
+```
+
+If not you might also need:
+```shell
+rtx install [email protected]
+rtx install node@16
+brew install vips
+npm install
+```
+
 ## Run project
-1. `npm install`
-2. `npm run develop`
+1. `npm run develop`
 
 ## Building
 `npm run build`

docs/intro-get-started.md

@@ -20,7 +20,7 @@ You can find our `.proto` files at https://github.com/working-group-two/wgtwoapi
 
 Download the FileDescriptorSet for our APIs, which contains all our `.proto` files:
 ```shell
-curl -L 'https://github.com/working-group-two/wgtwoapis/blob/master/image.bin?raw=true' -o wgtwo.bin 
+curl -L 'https://github.com/working-group-two/wgtwoapis/blob/master/image.bin?raw=true' -o wgtwo.bin
 ```
 
 ## Set up gRPCurl
@@ -147,9 +147,9 @@ CLIENT_ID=${CLIENT_ID} CLIENT_SECRET=${CLIENT_SECRET} go run main.go
 ## What's next?
 
 ### I am building a subscriber product
-All APIs, except the event API, will require an access token obtained via the [Authorization Code Grant](/oauth-2-0/get-user-access-token/).
 
-By implementing this flow, your users can authenticate on our platform and grant consent to your application. Once this flow is up, and users have consented, you will start getting events.
+In the near future there will be a products API and consent API, where subscribers can programmatically consent to
+products to be enabled for their subscription.
 
 There is a special event named `CONSENT_REVOKE_EVENT` that you must listen for, as this will fire if the
 consent is removed by the user through e.g. customer support. See [support revoking consent](/oauth-2-0/support-revoking-consent/). This event does not require a explicit scope.

docs/number-lookup-api-reference.md

@@ -0,0 +1,9 @@
+---
+title: API reference
+topic: number lookup
+type: api-reference
+roles:
+  - THIRD_PARTY_DEVELOPER
+---
+
+<GithubCode fileUrl="https://github.com/working-group-two/wgtwoapis/blob/master/wgtwo/lookup/v0/number_lookup.proto" />

docs/number-lookup-how-to.md

@@ -0,0 +1,166 @@
+---
+title: Technical guide
+topic: number lookup
+type: how-to
+roles:
+  - THIRD_PARTY_DEVELOPER
+sourceExamples:
+  - examples/grpcurl/thirdpartydev/number-lookup/provider.sh
+  - examples/kotlin/thirdpartydev/number-lookup/src/main/kotlin/com/wgtwo/examples/thirdpartydev/provider/Provider.kt
+---
+
+# Number Lookup API - Technical Guide
+
+> **This guide will show you how to set up a Number Lookup Provider.**
+>
+> You should have an understanding of how this works before continuing,
+> see [Overview](number-lookup/setup-number-lookup-overview/).
+
+## Prerequisites
+
+This guide assumes you are able to create a OAuth 2.0 client and get an access token.
+
+See [Get client access token](https://docs.wgtwo.com/guide/oauth2/get-client-access-token.html) for how to get the
+access token.
+
+> **Note:** <br />
+> For testing using our sandbox endpoint, authentication headers may be skipped.
+
+### Required scope
+
+`lookup.number:read`
+
+## How to use the API
+When you connect to this API, you will get a stream of number lookup requests for which you should respond with
+information about the number.
+
+<CodeSnippet
+:grpcurl="$sourceExamplesMap['examples/grpcurl/thirdpartydev/number-lookup/provider.sh']"
+:kotlinDeps="['auth', 'lookup']"
+:kotlin="
+$sourceExamplesMap['examples/kotlin/thirdpartydev/number-lookup/src/main/kotlin/com/wgtwo/examples/thirdpartydev/provider/Provider.kt']"
+/>
+
+## Flow
+The API is implemented as a bidirectional gRPC service, where the provider responds to requests from the server.
+
+The Number Provider sets up one or more connections to our API. This connection should use keep-alive, and has a max
+connection age of one hour +/- a 10 % jitter. Once max connection age is reached, or any exception occurs, the
+connection should be re-established.
+
+> **Note:** <br />
+> Although the connection is set up from the provider to wg2, all requests are initiated from wg2.
+
+![](~/assets/images/number-lookup-flow.svg)
+
+Using round-robin, wg2 will send number lookup requests
+over these connections for which the provider will respond with the display name.
+
+Responses will be cached for a period of time to avoid unnecessary requests and latency.
+
+![](~/assets/images/number-lookup-sequence.svg)
+
+## Request / Response
+
+For matching the response to the original request, the provider must include the original request in the response.
+
+The returned display name may be empty if the provider does not have a display name for the number, and
+may be cached for the duration specified.
+
+### Request
+```prototext
+NumberLookupRequest {
+  id: "opaque string"
+  number {
+    e164: "+1234567890"
+  }
+}
+```
+
+### Response
+```prototext
+NumberLookupResponse {
+  number_lookup_request { } # Fields omitted for brevity
+
+  result {
+    name: "John Doe"
+  }
+}
+```
+
+### Response, upstream error
+```prototext
+NumberLookupResponse {
+  number_lookup_request { } # Fields omitted for brevity
+
+  error {
+    message: "Database unavailable"
+  }
+}
+```
+
+## Limitations for display name
+
+The display name returned must be max 60 characters, and may only contain the following:
+
+- alphanumeric (`a-z`, `A-Z`, `0-9`)
+- ` `&nbsp;(space), `-`, `_`
+- `.`, `!`, `%`, `*`, `'`, `+`, `~`, `` ` ``
+
+Characters not matching the above will be stripped.
+
+## Error handling
+
+If there are no healthy connections for the provider, the provider will be ignored.
+
+Should the provider fail to respond within the set deadline, it will be treated as if it returned an empty result.
+
+For upstream errors, the provider must return an error, accompanied by a descriptive, human-readable message.
+
+## Cache
+
+As part of the response, the provider can include a cache TTL.
+
+This is the time in seconds that the display name should be cached on the wg2 side.
+If not set, a default cache TTL documented in the proto file will be used.
+
+```prototext
+NumberLookupResponse {
+  number_lookup_request { } # Fields omitted for brevity
+
+  result {
+    name: "John Doe"
+  }
+
+  # Optional, set to default if not set
+  cache_control {
+    max_age {
+      seconds: 3600  # 1 hour, google.protobuf.Duration
+    }
+  }
+}
+```
+
+## Recommended gRPC connection settings
+
+| Setting                         | Value      | Description                        |
+|:--------------------------------|:-----------|------------------------------------|
+| keep-alive period               | 1 minute   | Must be ≥ 1 minute and ≤ 5 minutes |
+| keep-alive timeout              | 10 seconds |                                    |
+| permit keep-alive without calls | true       |                                    |
+
+### Keep-Alive
+
+The load balancer hosting api.wgtwo.com will silently drop connections if they have been idle for 350 seconds (5m 50s).
+
+To avoid this, the provider should send a keep-alive message every minute.
+
+## Continue reading
+
+* [API reference](/number-lookup/api-reference/)
+
+## Concepts
+
+* [gRPC concepts](https://grpc.io/docs/guides/concepts/)
+* [Kotlin gRPC tutorial](https://grpc.io/docs/languages/kotlin/basics/)
+* [Java gRPC stubs](https://grpc.io/docs/reference/java/generated-code/)

docs/number-lookup-overview.md

@@ -0,0 +1,63 @@
+---
+title: Overview
+topic: number lookup
+type: overview
+roles:
+  - THIRD_PARTY_DEVELOPER
+sourceExamples:
+  - examples/kotlin/thirdpartydev/number-lookup/src/main/kotlin/com/wgtwo/examples/thirdpartydev/provider/Provider.kt
+---
+
+# Number Lookup API
+
+This is an API used to connect a number provider to our number lookup service.
+
+## Intended audience
+
+This API is designed for third-party phone number information providers.
+
+This includes phone book services, spam detection services, and any other services that offer insights about phone
+numbers.
+
+## Usage
+
+When you integrate as a number information provider, you'll receive a lookup request that contains a phone number.
+Your task will be to classify them and provide a display name lookup.
+
+The information you provide will assist wg2 in enhancing the call experience, such as setting the display name for
+incoming calls.
+
+## Include display name as part of call setup
+
+### Get number information from provider
+When a subscriber receives a call over VoLTE, we will check if there is any configured Number Lookup Providers for the
+subscriber.
+
+![](~/assets/images/number-lookup-get-providers.svg)
+
+During call setup a number lookup request will be sent to each of the enabled Number Lookup Providers, if any.
+
+![](~/assets/images/number-lookup-overview-flow.svg)
+
+### Show display name
+
+If we have received any display name from the providers, we will show it to the subscriber.
+
+This will be visible in the call screen, as seen in the image below where the display name is "Potential Spam".
+
+![](~/assets/images/number-lookup-call.png)
+
+> **Note:**
+> If the phone has the number stored as a contact, the phone will typically use this.
+
+## Error handling
+
+If the provider returns a empty display name (no hit in the phonebook) or fails to respond within the deadline,
+the call will be displayed as usual.
+
+Results will be cached for a period of time to avoid unnecessary requests and latency.
+
+## Continue reading
+
+* [Technical Guide](/number-lookup/technical-guide/)
+* [API reference](/number-lookup/api-reference/)

docs/oauth2-create-client-how-to.md

@@ -16,7 +16,7 @@ This client is tied to a product in the _Developer Portal_.
 1. Sign in at https://developer.wgtwo.com
 2. Create an organization
 3. Create a product
-4. Go to the clients tab, and click `CREATE NEW CLIENT`
+4. Go to the `Technical integration` tab, and click `ADD OAUTH CLIENT`
 
 If you are creating a product for subscribers, you will need to fill in your redirect URIs as you will be using OAuth
 2.0's Authorization Code Flow.
@@ -34,19 +34,19 @@ For operator products this info is not required as you will be using the Client
 The returned credentials will be displayed only once, so make sure to save them.
 
 ## Set scopes
-1. Go to the `SCOPES` tab
-2. Enable the three standard OAuth 2.0 scopes
+1. Go to the `Technical integration` tab and click in navigation bar `Enable API scopes`.
+2. Enable the three standard OAuth 2.0 scopes.
 
 <g-image src="@/assets/images/auth-set-scopes.png" alt="Set scopes" />
 
 ## Enable product for operator
-1. Go to the `LISTING` tab
-2. Select the operators you want to make your product available for. Operators will then be able to enable this product for their subscribers. 
+1. Go to the `Product information` tab and click in navigation bar `Distribution and availability`.
+2. Select the operators you want to make your product available for. Operators will then be able to enable this product for their subscribers.
 
 ## That's it
 You can now start playing with our APIs!
 
 In order to get your product displayed in our market placed, you will need to fill in some extra information.
 But before you do that, please go ahead with your integration.
 
-All fields can be changed until you submit your product, so feel free to keep updating it. 
+All fields can be changed until you submit your product, so feel free to keep updating it.

docs/sipbreakout-how-to.md

@@ -14,7 +14,7 @@ sourceExamples:
 
 ## Prerequisites
 1. [An OAuth 2.0 client](/oauth-2-0/create-o-auth-2-0-client/)
-2. [An access token](/oauth-2-0/get-user-access-token)
+2. [An access token](/oauth-2-0/get-client-access-token)
 
 ## Overview
 This API enables PBX/TAS (Private Branch Exchange/Telephony Application Server) providers to plug their (SIP-enabled)

docs/webterminal-how-to.md

@@ -14,14 +14,12 @@ sourceExamples:
 
 ## Prerequisites
 1. [An OAuth 2.0 client](/oauth-2-0/create-o-auth-2-0-client/)
-2. [An access token](/oauth-2-0/get-user-access-token)
+2. [An access token](/oauth-2-0/get-client-access-token)
 
 ## Overview
 This API makes it possible to register a WebRTC terminal (or just Terminal) with our (voice) core, and then use it to make and receive calls just like a mobile phone does.
 
-> The **msisdn** associated with the Terminal is captured (and validated) during `OAuth` round trip. 
-
-In other words, the API enables development of a software phone fully integrated with our core. 
+In other words, the API enables development of a software phone fully integrated with our core.
 
 To access this API, your credentials must include `call.control.answer_and_initiate` scope.
 
@@ -47,7 +45,7 @@ For example, if you:
 2. initiate a call by pushing a `WebTerminalMessage` that contains an `Offer` to our core
 3. receive a `WebTerminalMessage` from our core containing `Ringing` followed by an `Answer`
 
-then 
+then
 
 4. your Terminal will know that the callee's phone¹ was first ringing, and then the callee answered the call.