Refactor sdk package structure

.golangci.yaml

@@ -106,3 +106,19 @@ issues:
     - linters:
         - gocritic
       text: "unnecessaryDefer:"
+    - path: pkg/api/speak/v1/speak.go
+      linters:
+        - staticcheck
+      text: SA1019
+    - path: pkg/api/manage/v1/manage.go
+      linters:
+        - staticcheck
+      text: SA1019
+    - path: pkg/client/live/legacy.go
+      linters:
+        - staticcheck
+      text: SA1019
+    - path: pkg/api/prerecorded/v1/legacy.go
+      linters:
+        - staticcheck
+      text: SA1019

README.md

@@ -10,8 +10,8 @@ Official Go SDK for [Deepgram](https://www.deepgram.com/). Start building with o
 - [Installation](#installation)
 - [Requirements](#requirements)
 - [Quickstarts](#quickstarts)
-  - [PreRecorded Audio Transcription Quickstart](#prerecorded-audio-transcription-quickstart)
-  - [Live Audio Transcription Quickstart](#live-audio-transcription-quickstart)
+  - [Speech-to-Text from PreRecorded Audio Quickstart](#prerecorded-audio-transcription-quickstart)
+  - [Speech-to-Text from Live/Streaming Audio Quickstart](#live-audio-transcription-quickstart)
 - [Examples](#examples)
 - [Logging](#logging)
 - [Testing](#testing)
@@ -25,35 +25,41 @@ This SDK implements the Deepgram API found at [https://developers.deepgram.com](
 
 Documentation for specifics about the structs, interfaces, and functions of this SDK can be found here: [Go SDK Documentation](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main)
 
-For documentation relating to Live Audio Transcription:
+For documentation relating to Speech-to-Text from Live/Streaming Audio:
 
-- Live Client - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/live](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/live)
-- Live API - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/live/v1](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/live/v1)
-- Live API Interfaces - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/live/v1/interfaces](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/live/v1/interfaces)
+- Live Client - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/listen/v1/websocket](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/listen/v1/websocket)
+- Live API - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/listen/v1/websocket](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/listen/v1/websocket)
+- Live API Interfaces - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/listen/v1/websocket/interfaces](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/listen/v1/websocket/interfaces)
 
-For documentation relating to PreRecorded Audio Transcription and Intelligence:
+For documentation relating to Speech-to-Text (and Intelligence) from PreRecorded Audio:
 
-- PreRecorded Client - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/prerecorded](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/prerecorded)
-- PreRecorded API - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/prerecorded/v1](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/prerecorded/v1)
-- PreRecorded API Interfaces - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/prerecorded/v1/interfaces](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/prerecorded/v1/interfaces)
+- PreRecorded Client - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/listen/v1/rest](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/listen/v1/rest)
+- PreRecorded API - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/listen/v1/rest](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/listen/v1/rest)
+- PreRecorded API Interfaces - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/listen/v1/rest/interfaces](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/listen/v1/rest/interfaces)
 
 For documentation relating to Text-to-Speech:
 
-- Speak Client - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/speak](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/speak)
-- Speak API - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/speak/v1](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/speak/v1)
-- Speak API Interfaces - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/speak/v1/interfaces](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/speak/v1/interfaces)
+- WebSocket:
+  - Speak REST Client - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/speak/v1/websocket](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/speak/v1/websocket)
+  - Speak REST API - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/speak/v1/websocket](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/speak/v1/websocket)
+  - Speak API Interfaces - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/speak/v1/websocket/interfaces](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/speak/v1/websocket/interfaces)
+
+- REST:
+  - Speak REST Client - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/speak/v1/rest](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/speak/v1/rest)
+  - Speak REST API - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/speak/v1/rest](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/speak/v1/rest)
+  - Speak API Interfaces - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/speak/v1/rest/interfaces](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/speak/v1/rest/interfaces)
 
 For documentation relating to Text Intelligence:
 
-- Analyze Client - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/analyze](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/analyze)
+- Analyze Client - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/analyze/v1](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/client/analyze/v1)
 - Analyze API - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/analyze/v1](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/analyze/v1)
 - Analyze API Interfaces - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/analyze/v1/interfaces](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/analyze/v1/interfaces)
 
 For documentation relating to Manage API:
 
-- Management Client - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/manage/live](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/manage/live)
+- Management Client - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/manage/v1](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/manage/v1)
 - Manage API - [https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/manage/v1](https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/api/manage/v1)
-- Manage API Interfaces -[https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/manage/live/v1/interfaces]( https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/manage/live/v1/interfaces)
+- Manage API Interfaces -[https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/manage/v1/interfaces]( https://pkg.go.dev/github.com/deepgram/deepgram-go-sdk@main/pkg/manage/v1/interfaces)
 
 ## Getting an API Key
 
@@ -118,7 +124,7 @@ transcriptOptions := interfaces.LiveTranscriptionOptions{
 
 // create a callback for transcription messages
 // for example, you can take a look at this example project:
-// https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/streaming/microphone/main.go
+// https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/speech-to-text/websocket/microphone/main.go
 
 // create the client
 dgClient, err := client.NewWithDefaults(ctx, transcriptOptions, callback)
@@ -141,22 +147,27 @@ There are examples for **every*- API call in this SDK. You can find all of these
 
 These examples provide:
 
-Speech-to-Text: PreRecorded Audio:
+Speech-to-Text - PreRecorded Audio:
+
+- From an Audio File - [examples/speech-to-text/rest/file](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/speech-to-text/rest/file/main.go)
+- From an URL - [examples/speech-to-text/rest/url](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/speech-to-text/rest/url/main.go)
+- From an Audio Stream - [examples/speech-to-text/rest/stream](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/speech-to-text/rest/stream/main.go)
+
+Speech-to-Text - Live Audio:
 
-- From an Audio File - [examples/prerecorded/file](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/prerecorded/file/main.go)
-- From an URL - [examples/prerecorded/url](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/prerecorded/url/main.go)
-- From an Audio Stream - [examples/prerecorded/stream](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/prerecorded/stream/main.go)
+- From a Microphone - [examples/speech-to-text/websocket/microphone](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/speech-to-text/websocket/microphone/main.go)
+- From an HTTP Endpoint - [examples/speech-to-text/websocket/http](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/speech-to-text/websocket/http/main.go)
 
-Speech-to-Text: Live Audio:
+Text-to-Speech - WebSocket
 
-- From a Microphone - [examples/streaming/microphone](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/streaming/microphone/main.go)
-- From an HTTP Endpoint - [examples/streaming/http](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/streaming/http/main.go)
+- Websocket Simple Example - [examples/text-to-speech/websocket/simple](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/text-to-speech/websocket/simple/main.go)
+- Interactive Websocket - [examples/text-to-speech/websocket/interactive](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/text-to-speech/websocket/interactive/main.go)
 
-Text-to-Speech
+Text-to-Speech - REST
 
-- Save audio to a Path - [examples/speak/save](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/speak/save/main.go)
-- Save audio to a user-defined Writer - [examples/speak/file](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/speak/file/main.go)
-- Save audio to a Stream/Buffer - [examples/speak/stream](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/speak/stream/main.go)
+- Save audio to a Path - [examples/text-to-speech/rest/file](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/text-to-speech/rest/file/main.go)
+- Save audio to a Stream/Buffer - [examples/text-to-speech/rest/stream](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/text-to-speech/rest/stream/main.go)
+- Save audio to a user-defined Writer - [examples/text-to-speech/rest/writer](https://github.com/deepgram/deepgram-go-sdk/blob/main/examples/text-to-speech/rest/writer/main.go)
 
 Management API exercise the full [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) operations for:
 

docs.go

@@ -20,11 +20,15 @@
 package sdk
 
 import (
-	_ "github.com/deepgram/deepgram-go-sdk/pkg/client/live"
-	_ "github.com/deepgram/deepgram-go-sdk/pkg/client/prerecorded"
-	_ "github.com/deepgram/deepgram-go-sdk/pkg/client/rest"
+	_ "github.com/deepgram/deepgram-go-sdk/pkg/client/analyze"
+	_ "github.com/deepgram/deepgram-go-sdk/pkg/client/listen"
+	_ "github.com/deepgram/deepgram-go-sdk/pkg/client/manage"
+	_ "github.com/deepgram/deepgram-go-sdk/pkg/client/speak"
 
-	_ "github.com/deepgram/deepgram-go-sdk/pkg/api/live/v1"
+	_ "github.com/deepgram/deepgram-go-sdk/pkg/api/analyze/v1"
+	_ "github.com/deepgram/deepgram-go-sdk/pkg/api/listen/v1/rest"
+	_ "github.com/deepgram/deepgram-go-sdk/pkg/api/listen/v1/websocket"
 	_ "github.com/deepgram/deepgram-go-sdk/pkg/api/manage/v1"
-	_ "github.com/deepgram/deepgram-go-sdk/pkg/api/prerecorded/v1"
+	_ "github.com/deepgram/deepgram-go-sdk/pkg/api/speak/v1/rest"
+	_ "github.com/deepgram/deepgram-go-sdk/pkg/api/speak/v1/websocket"
 )

examples/manage/invitations-new-RENAME/main.go

@@ -0,0 +1,121 @@
+// Copyright 2023-2024 Deepgram SDK contributors. All Rights Reserved.
+// Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+// SPDX-License-Identifier: MIT
+
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	api "github.com/deepgram/deepgram-go-sdk/pkg/api/manage/v1"
+	interfaces "github.com/deepgram/deepgram-go-sdk/pkg/api/manage/v1/interfaces"
+	client "github.com/deepgram/deepgram-go-sdk/pkg/client/manage"
+)
+
+func main() {
+	// init library
+	client.InitWithDefault()
+
+	// context
+	ctx := context.Background()
+
+	//client
+	dg := client.NewWithDefaults()
+	mgClient := api.New(dg)
+
+	// list projects
+	respList, err := mgClient.ListProjects(ctx)
+	if err != nil {
+		fmt.Printf("ListProjects failed. Err: %v\n", err)
+		os.Exit(1)
+	}
+
+	var projectID string
+	for _, item := range respList.Projects {
+		projectID = item.ProjectID
+		name := item.Name
+		fmt.Printf("ListProjects() - Name: %s, ID: %s\n", name, projectID)
+		break
+	}
+
+	// list invitations
+	respGet, err := mgClient.ListInvitations(ctx, projectID)
+	if err != nil {
+		fmt.Printf("ListInvitations failed. Err: %v\n", err)
+		os.Exit(1)
+	}
+
+	if len(respGet.Invites) == 0 {
+		fmt.Printf("ListInvitations() - No invitations found\n")
+	} else {
+		for _, item := range respGet.Invites {
+			id := item.Email
+			scope := item.Scope
+			fmt.Printf("ListInvitations() - ID: %s, Scope: %s\n", id, scope)
+		}
+	}
+
+	// send invite
+	respMessage, err := mgClient.SendInvitation(ctx, projectID, &interfaces.InvitationRequest{
+		Email: "[email protected]",
+		Scope: "member",
+	})
+	if err != nil {
+		fmt.Printf("SendInvitation failed. Err: %v\n", err)
+		os.Exit(1)
+	}
+	fmt.Printf("SendInvitation() - Result: %s\n", respMessage.Message)
+
+	// list invitations
+	respGet, err = mgClient.ListInvitations(ctx, projectID)
+	if err != nil {
+		fmt.Printf("ListInvitations failed. Err: %v\n", err)
+		os.Exit(1)
+	}
+
+	if len(respGet.Invites) == 0 {
+		fmt.Printf("ListInvitations() - No invitations found\n")
+	} else {
+		for _, item := range respGet.Invites {
+			id := item.Email
+			scope := item.Scope
+			fmt.Printf("ListInvitations() - ID: %s, Scope: %s\n", id, scope)
+		}
+	}
+
+	// delete invitation
+	respMessage, err = mgClient.DeleteInvitation(ctx, projectID, "[email protected]")
+	if err != nil {
+		fmt.Printf("DeleteInvitation failed. Err: %v\n", err)
+		os.Exit(1)
+	}
+	fmt.Printf("DeleteInvitation() - Result: %s\n", respMessage.Message)
+
+	// list invitations
+	respGet, err = mgClient.ListInvitations(ctx, projectID)
+	if err != nil {
+		fmt.Printf("ListInvitations failed. Err: %v\n", err)
+		os.Exit(1)
+	}
+
+	if len(respGet.Invites) == 0 {
+		fmt.Printf("ListInvitations() - No invitations found\n")
+	} else {
+		for _, item := range respGet.Invites {
+			id := item.Email
+			scope := item.Scope
+			fmt.Printf("ListInvitations() - ID: %s, Scope: %s\n", id, scope)
+		}
+	}
+
+	// There isnt an API call to add a member to a project. So will leave this commented out as an example
+	// Leave Project
+	// respMessage, err = mgClient.LeaveProject(ctx, projectID)
+	// if err != nil {
+	// 	fmt.Printf("LeaveProject failed. Err: %v\n", err)
+	// 	os.Exit(1)
+	// }
+	// fmt.Printf("LeaveProject() - Name: %s\n", respMessage.Message)
+}

examples/speech-to-text/rest/file-new-RENAME/main.go

@@ -0,0 +1,102 @@
+// Copyright 2023-2024 Deepgram SDK contributors. All Rights Reserved.
+// Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+// SPDX-License-Identifier: MIT
+
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+
+	prettyjson "github.com/hokaccha/go-prettyjson"
+
+	api "github.com/deepgram/deepgram-go-sdk/pkg/api/listen/v1/rest"
+	interfaces "github.com/deepgram/deepgram-go-sdk/pkg/client/interfaces"
+	client "github.com/deepgram/deepgram-go-sdk/pkg/client/listen"
+)
+
+const (
+	filePath string = "./Bueller-Life-moves-pretty-fast.mp3"
+)
+
+func main() {
+	// init library
+	client.Init(client.InitLib{
+		LogLevel: client.LogLevelTrace, // LogLevelStandard / LogLevelFull / LogLevelTrace
+	})
+
+	// Go context
+	ctx := context.Background()
+
+	// set the Transcription options
+	options := &interfaces.PreRecordedTranscriptionOptions{
+		Model:       "nova-2",
+		Punctuate:   true,
+		Paragraphs:  true,
+		SmartFormat: true,
+		Language:    "en-US",
+		Utterances:  true,
+	}
+
+	// create a Deepgram client
+	c := client.NewREST("", &interfaces.ClientOptions{
+		Host: "https://api.deepgram.com",
+	})
+	dg := api.New(c)
+
+	// example on how to send a custom header
+	// need to import (
+	//	 "github.com/deepgram/deepgram-go-sdk/pkg/client/interfaces"
+	// )
+	//
+	// headers := make(map[string][]string, 0)
+	// headers["MY-CUSTOM-HEADER"] = []string{"CUSTOM"}
+	// ctx = cfginterfaces.WithCustomHeaders(ctx, headers)
+	//
+	// example on how to send a custom parameter
+	// params := make(map[string][]string, 0)
+	// params["utterances"] = []string{"true"}
+	// ctx = cfginterfaces.WithCustomParameters(ctx, params)
+
+	// send/process file to Deepgram
+	res, err := dg.FromFile(ctx, filePath, options)
+	if err != nil {
+		if e, ok := err.(*interfaces.StatusError); ok {
+			fmt.Printf("DEEPGRAM ERROR:\n%s:\n%s\n", e.DeepgramError.ErrCode, e.DeepgramError.ErrMsg)
+		}
+		fmt.Printf("FromStream failed. Err: %v\n", err)
+		os.Exit(1)
+	}
+
+	data, err := json.Marshal(res)
+	if err != nil {
+		fmt.Printf("json.Marshal failed. Err: %v\n", err)
+		os.Exit(1)
+	}
+
+	// make the JSON pretty
+	prettyJSON, err := prettyjson.Format(data)
+	if err != nil {
+		fmt.Printf("prettyjson.Marshal failed. Err: %v\n", err)
+		os.Exit(1)
+	}
+	fmt.Printf("\n\nResult:\n%s\n\n", prettyJSON)
+
+	// dump example VTT
+	vtt, err := res.ToWebVTT()
+	if err != nil {
+		fmt.Printf("ToWebVTT failed. Err: %v\n", err)
+		os.Exit(1)
+	}
+	fmt.Printf("\n\n\nVTT:\n%s\n\n\n", vtt)
+
+	// dump example SRT
+	srt, err := res.ToSRT()
+	if err != nil {
+		fmt.Printf("ToSRT failed. Err: %v\n", err)
+		os.Exit(1)
+	}
+	fmt.Printf("\n\n\nSRT:\n%s\n\n\n", srt)
+}

examples/prerecorded/file/main.go → examples/speech-to-text/rest/file/main.go

@@ -12,9 +12,9 @@ import (
 
 	prettyjson "github.com/hokaccha/go-prettyjson"
 
-	prerecorded "github.com/deepgram/deepgram-go-sdk/pkg/api/prerecorded/v1"
+	prerecorded "github.com/deepgram/deepgram-go-sdk/pkg/api/prerecorded/v1" //lint:ignore
 	interfaces "github.com/deepgram/deepgram-go-sdk/pkg/client/interfaces"
-	client "github.com/deepgram/deepgram-go-sdk/pkg/client/prerecorded"
+	client "github.com/deepgram/deepgram-go-sdk/pkg/client/prerecorded" //lint:ignore
 )
 
 const (