client

package
v0.0.11 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 8, 2024 License: BSD-3-Clause Imports: 29 Imported by: 1

Documentation

Overview

Package client implements the REST API exposed by Paperless-ngx. Paperless-ngx is a document management system transforming physical documents into a searchable online archive.

Authentication

Multiple authentication schemes are supported:

Pagination

APIs returning lists of items support pagination (e.g. Client.ListDocuments). The ListOptions struct embedded in the API-specific options supports specifying the page to request. Pagination tokens are available via the Response struct.

Example (Filter)
cl := New(Options{ /* … */ })

var opt ListStoragePathsOptions

opt.Ordering.Field = "name"
opt.Name.ContainsIgnoringCase = String("sales")
opt.Path.StartsWithIgnoringCase = String("2019/")

for {
	got, resp, err := cl.ListStoragePaths(context.Background(), opt)
	if err != nil {
		log.Fatalf("Listing storage paths failed: %v", err)
	}

	for _, i := range got {
		log.Printf("%s (%d documents)", i.Name, i.DocumentCount)
	}

	if resp.NextPage == nil {
		break
	}

	opt.Page = resp.NextPage
}
Output:

Example (Pagination)
cl := New(Options{ /* … */ })

var opt ListDocumentsOptions
var all []Document

for {
	documents, resp, err := cl.ListDocuments(context.Background(), opt)
	if err != nil {
		log.Fatalf("Listing documents failed: %v", err)
	}

	all = append(all, documents...)

	if resp.NextPage == nil {
		break
	}

	opt.Page = resp.NextPage
}

log.Printf("Received %d documents in total.", len(all))
Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Bool

func Bool(v bool) *bool

Bool allocates a new bool value to store v and returns a pointer to it.

func DefaultWaitForTaskCondition

func DefaultWaitForTaskCondition(task *Task) error

DefaultWaitForTaskCondition waits for a terminal status (success, failure or revoked).

func Int

func Int(v int) *int

Int allocates a new int value to store v and returns a pointer to it.

func Int64

func Int64(v int64) *int64

Int64 allocates a new int64 value to store v and returns a pointer to it.

func String

func String(v string) *string

String allocates a new string value to store v and returns a pointer to it.

func Time

func Time(v time.Time) *time.Time

Time allocates a new time.Time value to store v and returns a pointer to it.

Types

type AuthMechanism

type AuthMechanism interface {
	// contains filtered or unexported methods
}

type CharFilterSpec

type CharFilterSpec struct {
	EqualsIgnoringCase     *string
	StartsWithIgnoringCase *string
	EndsWithIgnoringCase   *string
	ContainsIgnoringCase   *string
}

CharFilterSpec contains filters available on character/string fields. All comparison are case-insensitive.

func (CharFilterSpec) EncodeValues

func (s CharFilterSpec) EncodeValues(key string, v *url.Values) error

type Client

type Client struct {
	// contains filtered or unexported fields
}

func New

func New(opts Options) *Client

New creates a new client instance.

func (*Client) CreateCorrespondent

func (c *Client) CreateCorrespondent(ctx context.Context, data *CorrespondentFields) (*Correspondent, *Response, error)

func (*Client) CreateCustomField added in v0.0.5

func (c *Client) CreateCustomField(ctx context.Context, data *CustomFieldFields) (*CustomField, *Response, error)

func (*Client) CreateDocumentType

func (c *Client) CreateDocumentType(ctx context.Context, data *DocumentTypeFields) (*DocumentType, *Response, error)

func (*Client) CreateStoragePath

func (c *Client) CreateStoragePath(ctx context.Context, data *StoragePathFields) (*StoragePath, *Response, error)

func (*Client) CreateTag

func (c *Client) CreateTag(ctx context.Context, data *TagFields) (*Tag, *Response, error)

func (*Client) DeleteCorrespondent

func (c *Client) DeleteCorrespondent(ctx context.Context, id int64) (*Response, error)

func (*Client) DeleteCustomField added in v0.0.5

func (c *Client) DeleteCustomField(ctx context.Context, id int64) (*Response, error)

func (*Client) DeleteDocument

func (c *Client) DeleteDocument(ctx context.Context, id int64) (*Response, error)

func (*Client) DeleteDocumentType

func (c *Client) DeleteDocumentType(ctx context.Context, id int64) (*Response, error)

func (*Client) DeleteStoragePath

func (c *Client) DeleteStoragePath(ctx context.Context, id int64) (*Response, error)

func (*Client) DeleteTag

func (c *Client) DeleteTag(ctx context.Context, id int64) (*Response, error)

func (*Client) DownloadDocumentArchived

func (c *Client) DownloadDocumentArchived(ctx context.Context, w io.Writer, id int64) (*DownloadResult, *Response, error)

DownloadDocumentArchived retrieves an archived PDF/A file generated from the originally consumed file. The archived version may not be available and the API may return the original. [DownloadDocumentOriginal] for additional details.

func (*Client) DownloadDocumentOriginal

func (c *Client) DownloadDocumentOriginal(ctx context.Context, w io.Writer, id int64) (*DownloadResult, *Response, error)

DownloadDocumentOriginal retrieves the document in the format originally consumed by Paperless. The file format can be determined using [DownloadResult.ContentType].

The content of the document is written to the given writer. To verify that the document is complete (the HTTP request may have been terminated early) the size and/or checksum can be verified with [GetDocumentMetadata].

func (*Client) DownloadDocumentThumbnail

func (c *Client) DownloadDocumentThumbnail(ctx context.Context, w io.Writer, id int64) (*DownloadResult, *Response, error)

DownloadDocumentThumbnail retrieves a preview image of the document. See [DownloadDocumentOriginal] for additional details.

func (*Client) GetCorrespondent

func (c *Client) GetCorrespondent(ctx context.Context, id int64) (*Correspondent, *Response, error)

func (*Client) GetCurrentUser added in v0.0.6

func (c *Client) GetCurrentUser(ctx context.Context) (*User, *Response, error)

GetCurrentUser looks up the authenticated user.

func (*Client) GetCustomField added in v0.0.5

func (c *Client) GetCustomField(ctx context.Context, id int64) (*CustomField, *Response, error)

func (*Client) GetDocument

func (c *Client) GetDocument(ctx context.Context, id int64) (*Document, *Response, error)

func (*Client) GetDocumentMetadata

func (c *Client) GetDocumentMetadata(ctx context.Context, id int64) (*DocumentMetadata, *Response, error)

func (*Client) GetDocumentType

func (c *Client) GetDocumentType(ctx context.Context, id int64) (*DocumentType, *Response, error)

func (*Client) GetGroup added in v0.0.6

func (c *Client) GetGroup(ctx context.Context, id int64) (*Group, *Response, error)

func (*Client) GetLog

func (c *Client) GetLog(ctx context.Context, name string) ([]LogEntry, *Response, error)

GetLog retrieves all entries of the named log file.

func (*Client) GetStoragePath

func (c *Client) GetStoragePath(ctx context.Context, id int64) (*StoragePath, *Response, error)

func (*Client) GetTag

func (c *Client) GetTag(ctx context.Context, id int64) (*Tag, *Response, error)

func (*Client) GetTask

func (c *Client) GetTask(ctx context.Context, taskID string) (*Task, *Response, error)

func (*Client) GetUser added in v0.0.6

func (c *Client) GetUser(ctx context.Context, id int64) (*User, *Response, error)

func (*Client) ListAllCorrespondents added in v0.0.3

func (c *Client) ListAllCorrespondents(ctx context.Context, opts ListCorrespondentsOptions, handler func(context.Context, Correspondent) error) error

ListAllCorrespondents iterates over all correspondents matching the filters specified in opts, invoking handler for each.

func (*Client) ListAllCustomFields added in v0.0.5

func (c *Client) ListAllCustomFields(ctx context.Context, opts ListCustomFieldsOptions, handler func(context.Context, CustomField) error) error

ListAllCustomFields iterates over all custom fields matching the filters specified in opts, invoking handler for each.

func (*Client) ListAllDocumentTypes added in v0.0.3

func (c *Client) ListAllDocumentTypes(ctx context.Context, opts ListDocumentTypesOptions, handler func(context.Context, DocumentType) error) error

ListAllDocumentTypes iterates over all document types matching the filters specified in opts, invoking handler for each.

func (*Client) ListAllDocuments added in v0.0.3

func (c *Client) ListAllDocuments(ctx context.Context, opts ListDocumentsOptions, handler func(context.Context, Document) error) error

ListAllDocuments iterates over all documents matching the filters specified in opts, invoking handler for each.

func (*Client) ListAllGroups added in v0.0.6

func (c *Client) ListAllGroups(ctx context.Context, opts ListGroupsOptions, handler func(context.Context, Group) error) error

ListAllGroups iterates over all groups matching the filters specified in opts, invoking handler for each.

func (*Client) ListAllStoragePaths added in v0.0.3

func (c *Client) ListAllStoragePaths(ctx context.Context, opts ListStoragePathsOptions, handler func(context.Context, StoragePath) error) error

ListAllStoragePaths iterates over all storage paths matching the filters specified in opts, invoking handler for each.

func (*Client) ListAllTags added in v0.0.3

func (c *Client) ListAllTags(ctx context.Context, opts ListTagsOptions, handler func(context.Context, Tag) error) error

ListAllTags iterates over all tags matching the filters specified in opts, invoking handler for each.

func (*Client) ListAllUsers added in v0.0.6

func (c *Client) ListAllUsers(ctx context.Context, opts ListUsersOptions, handler func(context.Context, User) error) error

ListAllUsers iterates over all users matching the filters specified in opts, invoking handler for each.

func (*Client) ListCorrespondents

func (c *Client) ListCorrespondents(ctx context.Context, opts ListCorrespondentsOptions) ([]Correspondent, *Response, error)

func (*Client) ListCustomFields added in v0.0.5

func (c *Client) ListCustomFields(ctx context.Context, opts ListCustomFieldsOptions) ([]CustomField, *Response, error)

func (*Client) ListDocumentTypes

func (c *Client) ListDocumentTypes(ctx context.Context, opts ListDocumentTypesOptions) ([]DocumentType, *Response, error)

func (*Client) ListDocuments

func (c *Client) ListDocuments(ctx context.Context, opts ListDocumentsOptions) ([]Document, *Response, error)

func (*Client) ListGroups added in v0.0.6

func (c *Client) ListGroups(ctx context.Context, opts ListGroupsOptions) ([]Group, *Response, error)

func (*Client) ListLogs

func (c *Client) ListLogs(ctx context.Context) ([]string, *Response, error)

ListLogs retrieves the names of available log files.

func (*Client) ListStoragePaths

func (c *Client) ListStoragePaths(ctx context.Context, opts ListStoragePathsOptions) ([]StoragePath, *Response, error)

func (*Client) ListTags

func (c *Client) ListTags(ctx context.Context, opts ListTagsOptions) ([]Tag, *Response, error)

func (*Client) ListTasks

func (c *Client) ListTasks(ctx context.Context) ([]Task, *Response, error)

func (*Client) ListUsers added in v0.0.6

func (c *Client) ListUsers(ctx context.Context, opts ListUsersOptions) ([]User, *Response, error)

func (*Client) PatchCorrespondent added in v0.0.5

func (c *Client) PatchCorrespondent(ctx context.Context, id int64, data *CorrespondentFields) (*Correspondent, *Response, error)

func (*Client) PatchCustomField added in v0.0.5

func (c *Client) PatchCustomField(ctx context.Context, id int64, data *CustomFieldFields) (*CustomField, *Response, error)

func (*Client) PatchDocument added in v0.0.6

func (c *Client) PatchDocument(ctx context.Context, id int64, data *DocumentFields) (*Document, *Response, error)

func (*Client) PatchDocumentType added in v0.0.5

func (c *Client) PatchDocumentType(ctx context.Context, id int64, data *DocumentTypeFields) (*DocumentType, *Response, error)

func (*Client) PatchStoragePath added in v0.0.5

func (c *Client) PatchStoragePath(ctx context.Context, id int64, data *StoragePathFields) (*StoragePath, *Response, error)

func (*Client) PatchTag added in v0.0.5

func (c *Client) PatchTag(ctx context.Context, id int64, data *TagFields) (*Tag, *Response, error)

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) error

Ping tests whether the API is available.

func (*Client) UpdateCorrespondent

func (c *Client) UpdateCorrespondent(ctx context.Context, id int64, data *Correspondent) (*Correspondent, *Response, error)

func (*Client) UpdateCustomField added in v0.0.5

func (c *Client) UpdateCustomField(ctx context.Context, id int64, data *CustomField) (*CustomField, *Response, error)

func (*Client) UpdateDocument

func (c *Client) UpdateDocument(ctx context.Context, id int64, data *Document) (*Document, *Response, error)

func (*Client) UpdateDocumentType

func (c *Client) UpdateDocumentType(ctx context.Context, id int64, data *DocumentType) (*DocumentType, *Response, error)

func (*Client) UpdateStoragePath

func (c *Client) UpdateStoragePath(ctx context.Context, id int64, data *StoragePath) (*StoragePath, *Response, error)

func (*Client) UpdateTag

func (c *Client) UpdateTag(ctx context.Context, id int64, data *Tag) (*Tag, *Response, error)

func (*Client) UploadDocument

func (c *Client) UploadDocument(ctx context.Context, r io.Reader, opts DocumentUploadOptions) (*DocumentUpload, *Response, error)

Upload a file. Returns immediately and without error if the document consumption process was started successfully. No additional status information about the consumption process is available immediately. Poll the returned task ID to wait for the consumption.

func (*Client) WaitForTask

func (c *Client) WaitForTask(ctx context.Context, taskID string, opts WaitForTaskOptions) (*Task, error)

WaitForTask polls the status of a task until it reaches a terminal status (success, failure or revoked). Task failures are reported as an error of type TaskError.

type Color

type Color struct {
	R, G, B uint8
}

func NewColor

func NewColor(src color.Color) Color

NewColor converts any color implementing the color.Color interface.

func (Color) MarshalJSON

func (c Color) MarshalJSON() ([]byte, error)

func (Color) RGBA

func (c Color) RGBA() (r, g, b, a uint32)

RGBA implements color.Color.RGBA.

func (*Color) UnmarshalJSON

func (c *Color) UnmarshalJSON(data []byte) error

type Correspondent

type Correspondent struct {
	ID                 int64             `json:"id"`
	Slug               string            `json:"slug"`
	Name               string            `json:"name"`
	Match              string            `json:"match"`
	MatchingAlgorithm  MatchingAlgorithm `json:"matching_algorithm"`
	IsInsensitive      bool              `json:"is_insensitive"`
	DocumentCount      int64             `json:"document_count"`
	LastCorrespondence *time.Time        `json:"last_correspondence"`

	// Object owner; objects without owner can be viewed and edited by all users.
	Owner *int64 `json:"owner"`
}

type CorrespondentFields added in v0.0.5

type CorrespondentFields struct {
	// contains filtered or unexported fields
}

func NewCorrespondentFields added in v0.0.5

func NewCorrespondentFields() *CorrespondentFields

func (CorrespondentFields) AsMap added in v0.0.6

func (f CorrespondentFields) AsMap() map[string]any

AsMap returns a map from object field name to value.

func (CorrespondentFields) MarshalJSON added in v0.0.5

func (f CorrespondentFields) MarshalJSON() ([]byte, error)

func (*CorrespondentFields) SetIsInsensitive added in v0.0.6

func (f *CorrespondentFields) SetIsInsensitive(isInsensitive bool) *CorrespondentFields

SetIsInsensitive sets the "is_insensitive" field.

func (*CorrespondentFields) SetMatch added in v0.0.6

func (f *CorrespondentFields) SetMatch(match string) *CorrespondentFields

SetMatch sets the "match" field.

func (*CorrespondentFields) SetMatchingAlgorithm added in v0.0.6

func (f *CorrespondentFields) SetMatchingAlgorithm(matchingAlgorithm MatchingAlgorithm) *CorrespondentFields

SetMatchingAlgorithm sets the "matching_algorithm" field.

func (*CorrespondentFields) SetName added in v0.0.6

SetName sets the "name" field.

func (*CorrespondentFields) SetOwner added in v0.0.6

func (f *CorrespondentFields) SetOwner(owner *int64) *CorrespondentFields

SetOwner sets the "owner" field.

Object owner; objects without owner can be viewed and edited by all users.

func (*CorrespondentFields) SetSetPermissions added in v0.0.6

func (f *CorrespondentFields) SetSetPermissions(setPermissions *ObjectPermissions) *CorrespondentFields

SetSetPermissions sets the "set_permissions" field.

Change object-level permissions.

type CustomField added in v0.0.5

type CustomField struct {
	ID       int64  `json:"id"`
	Name     string `json:"name"`
	DataType string `json:"data_type"`

	// Object owner; objects without owner can be viewed and edited by all users.
	Owner *int64 `json:"owner"`
}

type CustomFieldFields added in v0.0.5

type CustomFieldFields struct {
	// contains filtered or unexported fields
}

func NewCustomFieldFields added in v0.0.5

func NewCustomFieldFields() *CustomFieldFields

func (CustomFieldFields) AsMap added in v0.0.6

func (f CustomFieldFields) AsMap() map[string]any

AsMap returns a map from object field name to value.

func (CustomFieldFields) MarshalJSON added in v0.0.5

func (f CustomFieldFields) MarshalJSON() ([]byte, error)

func (*CustomFieldFields) SetDataType added in v0.0.6

func (f *CustomFieldFields) SetDataType(dataType string) *CustomFieldFields

SetDataType sets the "data_type" field.

func (*CustomFieldFields) SetName added in v0.0.6

func (f *CustomFieldFields) SetName(name string) *CustomFieldFields

SetName sets the "name" field.

func (*CustomFieldFields) SetOwner added in v0.0.6

func (f *CustomFieldFields) SetOwner(owner *int64) *CustomFieldFields

SetOwner sets the "owner" field.

Object owner; objects without owner can be viewed and edited by all users.

func (*CustomFieldFields) SetSetPermissions added in v0.0.6

func (f *CustomFieldFields) SetSetPermissions(setPermissions *ObjectPermissions) *CustomFieldFields

SetSetPermissions sets the "set_permissions" field.

Change object-level permissions.

type CustomFieldInstance added in v0.0.5

type CustomFieldInstance struct {
	Field int64 `json:"field"`
	Value any   `json:"value"`
}

type DateTimeFilterSpec

type DateTimeFilterSpec struct {
	// Set to a non-nil value to only include newer items.
	Gt *time.Time

	// Set to a non-nil value to only include older items.
	Lt *time.Time
}

func (DateTimeFilterSpec) EncodeValues

func (s DateTimeFilterSpec) EncodeValues(key string, v *url.Values) error

type Document

type Document struct {
	// ID of the document.
	ID int64 `json:"id"`

	// Title of the document.
	Title string `json:"title"`

	// Plain-text content of the document.
	Content string `json:"content"`

	// List of tag IDs assigned to this document, or empty list.
	Tags []int64 `json:"tags"`

	// Document type of this document or nil.
	DocumentType *int64 `json:"document_type"`

	// Correspondent of this document or nil.
	Correspondent *int64 `json:"correspondent"`

	// Storage path of this document or nil.
	StoragePath *int64 `json:"storage_path"`

	// The date time at which this document was created.
	Created time.Time `json:"created"`

	// The date at which this document was last edited in paperless.
	Modified time.Time `json:"modified"`

	// The date at which this document was added to paperless.
	Added time.Time `json:"added"`

	// The identifier of this document in a physical document archive.
	ArchiveSerialNumber *int64 `json:"archive_serial_number"`

	// Verbose filename of the original document.
	OriginalFileName string `json:"original_file_name"`

	// Verbose filename of the archived document. Nil if no archived document is available.
	ArchivedFileName *string `json:"archived_file_name"`

	// Custom fields on the document.
	CustomFields []CustomFieldInstance `json:"custom_fields"`

	// Object owner; objects without owner can be viewed and edited by all users.
	Owner *int64 `json:"owner"`
}

type DocumentFields added in v0.0.6

type DocumentFields struct {
	// contains filtered or unexported fields
}

func NewDocumentFields added in v0.0.6

func NewDocumentFields() *DocumentFields

func (DocumentFields) AsMap added in v0.0.6

func (f DocumentFields) AsMap() map[string]any

AsMap returns a map from object field name to value.

func (DocumentFields) MarshalJSON added in v0.0.6

func (f DocumentFields) MarshalJSON() ([]byte, error)

func (*DocumentFields) SetArchiveSerialNumber added in v0.0.6

func (f *DocumentFields) SetArchiveSerialNumber(archiveSerialNumber *int64) *DocumentFields

SetArchiveSerialNumber sets the "archive_serial_number" field.

The identifier of this document in a physical document archive.

func (*DocumentFields) SetContent added in v0.0.6

func (f *DocumentFields) SetContent(content string) *DocumentFields

SetContent sets the "content" field.

Plain-text content of the document.

func (*DocumentFields) SetCorrespondent added in v0.0.6

func (f *DocumentFields) SetCorrespondent(correspondent *int64) *DocumentFields

SetCorrespondent sets the "correspondent" field.

Correspondent of this document or nil.

func (*DocumentFields) SetCreated added in v0.0.6

func (f *DocumentFields) SetCreated(created time.Time) *DocumentFields

SetCreated sets the "created" field.

The date time at which this document was created.

func (*DocumentFields) SetCustomFields added in v0.0.6

func (f *DocumentFields) SetCustomFields(customFields []CustomFieldInstance) *DocumentFields

SetCustomFields sets the "custom_fields" field.

Custom fields on the document.

func (*DocumentFields) SetDocumentType added in v0.0.6

func (f *DocumentFields) SetDocumentType(documentType *int64) *DocumentFields

SetDocumentType sets the "document_type" field.

Document type of this document or nil.

func (*DocumentFields) SetOwner added in v0.0.6

func (f *DocumentFields) SetOwner(owner *int64) *DocumentFields

SetOwner sets the "owner" field.

Object owner; objects without owner can be viewed and edited by all users.

func (*DocumentFields) SetSetPermissions added in v0.0.6

func (f *DocumentFields) SetSetPermissions(setPermissions *ObjectPermissions) *DocumentFields

SetSetPermissions sets the "set_permissions" field.

Change object-level permissions.

func (*DocumentFields) SetStoragePath added in v0.0.6

func (f *DocumentFields) SetStoragePath(storagePath *int64) *DocumentFields

SetStoragePath sets the "storage_path" field.

Storage path of this document or nil.

func (*DocumentFields) SetTags added in v0.0.6

func (f *DocumentFields) SetTags(tags []int64) *DocumentFields

SetTags sets the "tags" field.

List of tag IDs assigned to this document, or empty list.

func (*DocumentFields) SetTitle added in v0.0.6

func (f *DocumentFields) SetTitle(title string) *DocumentFields

SetTitle sets the "title" field.

Title of the document.

type DocumentMetadata

type DocumentMetadata struct {
	OriginalFilename      string                    `json:"original_filename"`
	OriginalMediaFilename string                    `json:"media_filename"`
	OriginalChecksum      string                    `json:"original_checksum"`
	OriginalSize          int64                     `json:"original_size"`
	OriginalMimeType      string                    `json:"original_mime_type"`
	OriginalMetadata      []DocumentVersionMetadata `json:"original_metadata"`

	HasArchiveVersion    bool                      `json:"has_archive_version"`
	ArchiveMediaFilename string                    `json:"archive_media_filename"`
	ArchiveChecksum      string                    `json:"archive_checksum"`
	ArchiveSize          int64                     `json:"archive_size"`
	ArchiveMetadata      []DocumentVersionMetadata `json:"archive_metadata"`

	Language string `json:"lang"`
}

type DocumentType

type DocumentType struct {
	ID                int64             `json:"id"`
	Slug              string            `json:"slug"`
	Name              string            `json:"name"`
	Match             string            `json:"match"`
	MatchingAlgorithm MatchingAlgorithm `json:"matching_algorithm"`
	IsInsensitive     bool              `json:"is_insensitive"`
	DocumentCount     int64             `json:"document_count"`

	// Object owner; objects without owner can be viewed and edited by all users.
	Owner *int64 `json:"owner"`
}

type DocumentTypeFields added in v0.0.5

type DocumentTypeFields struct {
	// contains filtered or unexported fields
}

func NewDocumentTypeFields added in v0.0.5

func NewDocumentTypeFields() *DocumentTypeFields

func (DocumentTypeFields) AsMap added in v0.0.6

func (f DocumentTypeFields) AsMap() map[string]any

AsMap returns a map from object field name to value.

func (DocumentTypeFields) MarshalJSON added in v0.0.5

func (f DocumentTypeFields) MarshalJSON() ([]byte, error)

func (*DocumentTypeFields) SetIsInsensitive added in v0.0.6

func (f *DocumentTypeFields) SetIsInsensitive(isInsensitive bool) *DocumentTypeFields

SetIsInsensitive sets the "is_insensitive" field.

func (*DocumentTypeFields) SetMatch added in v0.0.6

func (f *DocumentTypeFields) SetMatch(match string) *DocumentTypeFields

SetMatch sets the "match" field.

func (*DocumentTypeFields) SetMatchingAlgorithm added in v0.0.6

func (f *DocumentTypeFields) SetMatchingAlgorithm(matchingAlgorithm MatchingAlgorithm) *DocumentTypeFields

SetMatchingAlgorithm sets the "matching_algorithm" field.

func (*DocumentTypeFields) SetName added in v0.0.6

func (f *DocumentTypeFields) SetName(name string) *DocumentTypeFields

SetName sets the "name" field.

func (*DocumentTypeFields) SetOwner added in v0.0.6

func (f *DocumentTypeFields) SetOwner(owner *int64) *DocumentTypeFields

SetOwner sets the "owner" field.

Object owner; objects without owner can be viewed and edited by all users.

func (*DocumentTypeFields) SetSetPermissions added in v0.0.6

func (f *DocumentTypeFields) SetSetPermissions(setPermissions *ObjectPermissions) *DocumentTypeFields

SetSetPermissions sets the "set_permissions" field.

Change object-level permissions.

type DocumentUpload

type DocumentUpload struct {
	TaskID string
}

type DocumentUploadOptions

type DocumentUploadOptions struct {
	Filename string `url:"-"`

	// Title for the document.
	Title string `url:"title,omitempty"`

	// Datetime at which the document was created.
	Created time.Time `url:"created,omitempty"`

	// ID of a correspondent for the document.
	Correspondent *int64 `url:"correspondent,omitempty"`

	// ID of a document type for the document.
	DocumentType *int64 `url:"document_type,omitempty"`

	// ID of a storage path for the document.
	StoragePath *int64 `url:"storage_path,omitempty"`

	// Tag IDs for the document.
	Tags []int64 `url:"tags,omitempty"`

	// Archive serial number to set on the document.
	ArchiveSerialNumber *int64 `url:"archive_serial_number,omitempty"`
}

type DocumentVersionMetadata

type DocumentVersionMetadata struct {
	Namespace string `json:"namespace"`
	Prefix    string `json:"prefix"`
	Key       string `json:"key"`
	Value     string `json:"value"`
}

type DownloadResult

type DownloadResult struct {
	// MIME content type (e.g. "application/pdf").
	ContentType string

	// Parameters for body content type (e.g. "charset").
	ContentTypeParams map[string]string

	// The preferred filename as reported by the server (if any).
	Filename string

	// Length of the downloaded body in bytes.
	Length int64
}

type Flags

type Flags struct {
	// Whether to enable verbose log messages.
	DebugMode bool

	// HTTP(S) URL for Paperless.
	BaseURL string

	// Number of concurrent requests allowed to be in flight.
	MaxConcurrentRequests int

	// Authenticate via token.
	AuthToken string

	// Read the authentication token from a file.
	AuthTokenFile string

	// Authenticate via HTTP basic authentication (username and password).
	AuthUsername string
	AuthPassword string

	// Read the password from a file.
	AuthPasswordFile string

	// Authenticate using OpenID Connect (OIDC) ID tokens derived from a Google
	// Cloud Platform service account key file.
	AuthGCPServiceAccountKeyFile string

	// Target audience for OpenID Connect (OIDC) ID tokens. May be left empty,
	// in which case the Paperless URL is used verbatim.
	AuthOIDCIDTokenAudience string

	// HTTP headers to set on all requests.
	Header http.Header

	// Timezone for parsing timestamps without offset.
	ServerTimezone string
}

Flags contains attributes to construct a Paperless client instance. The separate "kpflag" package implements bindings for github.com/alecthomas/kingpin/v2.

func (*Flags) Build

func (f *Flags) Build() (*Client, error)

Build returns a fully configured Paperless client derived from flags.

func (*Flags) BuildOptions

func (f *Flags) BuildOptions() (*Options, error)

BuildOptions returns the client options derived from flags.

type ForeignKeyFilterSpec

type ForeignKeyFilterSpec struct {
	IsNull *bool
	ID     *int64
	Name   CharFilterSpec
}

func (ForeignKeyFilterSpec) EncodeValues

func (s ForeignKeyFilterSpec) EncodeValues(key string, v *url.Values) error

type GCPServiceAccountKeyAuth added in v0.0.9

type GCPServiceAccountKeyAuth struct {
	// Path to a file containing the service account key.
	KeyFile string

	// Service account key in JSON format.
	Key []byte

	// Audience to request for the ID token (case-sensitive). If empty the
	// Paperless URL is used verbatim.
	Audience string

	// Custom HTTP client for requesting tokens.
	HTTPClient *http.Client
}

GCPServiceAccountKeyAuth uses a Google Cloud Platform service account key file to authenticate against an OAuth 2.0-protected Paperless instance using the two-legged JWT flow.

The service account key is used to request OpenID Connect (OIDC) ID tokens from the Google OAuth 2.0 API. The ID tokens are in turn used for all Paperless API requests.

References:

func (GCPServiceAccountKeyAuth) Build added in v0.0.9

type Group added in v0.0.6

type Group struct {
	ID   int64  `json:"id"`
	Name string `json:"name"`
}

type GroupFields added in v0.0.6

type GroupFields struct {
	// contains filtered or unexported fields
}

func NewGroupFields added in v0.0.6

func NewGroupFields() *GroupFields

func (GroupFields) AsMap added in v0.0.6

func (f GroupFields) AsMap() map[string]any

AsMap returns a map from object field name to value.

func (GroupFields) MarshalJSON added in v0.0.6

func (f GroupFields) MarshalJSON() ([]byte, error)

func (*GroupFields) SetName added in v0.0.6

func (f *GroupFields) SetName(name string) *GroupFields

SetName sets the "name" field.

type IntFilterSpec

type IntFilterSpec struct {
	Equals *int64
	Gt     *int64
	Gte    *int64
	Lt     *int64
	Lte    *int64
	IsNull *bool
}

IntFilterSpec contains filters available on numeric fields.

func (IntFilterSpec) EncodeValues

func (s IntFilterSpec) EncodeValues(key string, v *url.Values) error

type ListCorrespondentsOptions

type ListCorrespondentsOptions struct {
	ListOptions

	Ordering OrderingSpec   `url:"ordering"`
	Owner    IntFilterSpec  `url:"owner"`
	Name     CharFilterSpec `url:"name"`
}

type ListCustomFieldsOptions added in v0.0.5

type ListCustomFieldsOptions struct {
	ListOptions
}

type ListDocumentTypesOptions

type ListDocumentTypesOptions struct {
	ListOptions

	Ordering OrderingSpec   `url:"ordering"`
	Owner    IntFilterSpec  `url:"owner"`
	Name     CharFilterSpec `url:"name"`
}

type ListDocumentsOptions

type ListDocumentsOptions struct {
	ListOptions

	Ordering            OrderingSpec         `url:"ordering"`
	Owner               IntFilterSpec        `url:"owner"`
	Title               CharFilterSpec       `url:"title"`
	Content             CharFilterSpec       `url:"content"`
	ArchiveSerialNumber IntFilterSpec        `url:"archive_serial_number"`
	Created             DateTimeFilterSpec   `url:"created"`
	Added               DateTimeFilterSpec   `url:"added"`
	Modified            DateTimeFilterSpec   `url:"modified"`
	Correspondent       ForeignKeyFilterSpec `url:"correspondent"`
	Tags                ForeignKeyFilterSpec `url:"tags"`
	DocumentType        ForeignKeyFilterSpec `url:"document_type"`
	StoragePath         ForeignKeyFilterSpec `url:"storage_path"`
}

type ListGroupsOptions added in v0.0.6

type ListGroupsOptions struct {
	ListOptions

	Ordering OrderingSpec   `url:"ordering"`
	Name     CharFilterSpec `url:"name"`
}

type ListOptions

type ListOptions struct {
	Page *PageToken
}

type ListStoragePathsOptions

type ListStoragePathsOptions struct {
	ListOptions

	Ordering OrderingSpec   `url:"ordering"`
	Owner    IntFilterSpec  `url:"owner"`
	Name     CharFilterSpec `url:"name"`
	Path     CharFilterSpec `url:"path"`
}

type ListTagsOptions

type ListTagsOptions struct {
	ListOptions

	Ordering OrderingSpec   `url:"ordering"`
	Owner    IntFilterSpec  `url:"owner"`
	Name     CharFilterSpec `url:"name"`
}

type ListUsersOptions added in v0.0.6

type ListUsersOptions struct {
	ListOptions

	Ordering OrderingSpec   `url:"ordering"`
	Username CharFilterSpec `url:"username"`
}

type LogEntry

type LogEntry struct {
	Time    time.Time
	Level   string
	Module  string
	Message string
}

type Logger

type Logger interface {
	Errorf(format string, v ...any)
	Warnf(format string, v ...any)
	Debugf(format string, v ...any)
}

type MatchingAlgorithm

type MatchingAlgorithm int
const (
	// None.
	MatchNone MatchingAlgorithm = iota

	// Any word.
	MatchAny

	// All words.
	MatchAll

	// Exact match.
	MatchLiteral

	// Regular expression.
	MatchRegex

	// Fuzzy word.
	MatchFuzzy

	// Automatic using a document classification model.
	MatchAuto
)

func (MatchingAlgorithm) String

func (i MatchingAlgorithm) String() string

type ObjectPermissionPrincipals added in v0.0.6

type ObjectPermissionPrincipals struct {
	Users  []int64 `json:"users"`
	Groups []int64 `json:"groups"`
}

type ObjectPermissions added in v0.0.6

type ObjectPermissions struct {
	View   ObjectPermissionPrincipals `json:"view"`
	Change ObjectPermissionPrincipals `json:"change"`
}

type Options

type Options struct {
	// Paperless URL. May include a path.
	BaseURL string

	// API authentication.
	Auth AuthMechanism

	// Enable debug mode with many details logged.
	DebugMode bool

	// Logger for writing log messages. If debug mode is enabled and no logger
	// is configured all messages are written to standard library's default
	// logger (log.Default()).
	Logger Logger

	// HTTP headers to set on all requests.
	Header http.Header

	// Server's timezone for parsing timestamps without explicit offset.
	// Defaults to [time.Local].
	ServerLocation *time.Location

	// Number of concurrent requests allowed to be in flight. Defaults to zero
	// (no limitation).
	MaxConcurrentRequests int
	// contains filtered or unexported fields
}

Options for constructing a Paperless client.

type OrderingSpec

type OrderingSpec struct {
	// Field name, e.g. "created".
	Field string

	// Set to true for descending order. Ascending is the default.
	Desc bool
}

OrderingSpec controls the sorting order for lists.

func (OrderingSpec) EncodeValues

func (o OrderingSpec) EncodeValues(key string, v *url.Values) error

type PageToken

type PageToken struct {
	// contains filtered or unexported fields
}

func (*PageToken) EncodeValues

func (t *PageToken) EncodeValues(_ string, v *url.Values) error

type RequestError

type RequestError struct {
	StatusCode int
	Message    string
}

func (*RequestError) Error

func (e *RequestError) Error() string

func (*RequestError) Is

func (e *RequestError) Is(other error) bool

type Response

type Response struct {
	*http.Response

	// Token for fetching next page in paginated result sets.
	NextPage *PageToken

	// Token for fetching previous page in paginated result sets.
	PrevPage *PageToken
}

type StoragePath

type StoragePath struct {
	ID                int64             `json:"id"`
	Slug              string            `json:"slug"`
	Name              string            `json:"name"`
	Match             string            `json:"match"`
	MatchingAlgorithm MatchingAlgorithm `json:"matching_algorithm"`
	IsInsensitive     bool              `json:"is_insensitive"`
	DocumentCount     int64             `json:"document_count"`

	// Object owner; objects without owner can be viewed and edited by all users.
	Owner *int64 `json:"owner"`
}

type StoragePathFields added in v0.0.5

type StoragePathFields struct {
	// contains filtered or unexported fields
}

func NewStoragePathFields added in v0.0.5

func NewStoragePathFields() *StoragePathFields

func (StoragePathFields) AsMap added in v0.0.6

func (f StoragePathFields) AsMap() map[string]any

AsMap returns a map from object field name to value.

func (StoragePathFields) MarshalJSON added in v0.0.5

func (f StoragePathFields) MarshalJSON() ([]byte, error)

func (*StoragePathFields) SetIsInsensitive added in v0.0.6

func (f *StoragePathFields) SetIsInsensitive(isInsensitive bool) *StoragePathFields

SetIsInsensitive sets the "is_insensitive" field.

func (*StoragePathFields) SetMatch added in v0.0.6

func (f *StoragePathFields) SetMatch(match string) *StoragePathFields

SetMatch sets the "match" field.

func (*StoragePathFields) SetMatchingAlgorithm added in v0.0.6

func (f *StoragePathFields) SetMatchingAlgorithm(matchingAlgorithm MatchingAlgorithm) *StoragePathFields

SetMatchingAlgorithm sets the "matching_algorithm" field.

func (*StoragePathFields) SetName added in v0.0.6

func (f *StoragePathFields) SetName(name string) *StoragePathFields

SetName sets the "name" field.

func (*StoragePathFields) SetOwner added in v0.0.6

func (f *StoragePathFields) SetOwner(owner *int64) *StoragePathFields

SetOwner sets the "owner" field.

Object owner; objects without owner can be viewed and edited by all users.

func (*StoragePathFields) SetSetPermissions added in v0.0.6

func (f *StoragePathFields) SetSetPermissions(setPermissions *ObjectPermissions) *StoragePathFields

SetSetPermissions sets the "set_permissions" field.

Change object-level permissions.

type Tag

type Tag struct {
	ID                int64             `json:"id"`
	Slug              string            `json:"slug"`
	Name              string            `json:"name"`
	Color             Color             `json:"color"`
	TextColor         Color             `json:"text_color"`
	Match             string            `json:"match"`
	MatchingAlgorithm MatchingAlgorithm `json:"matching_algorithm"`
	IsInsensitive     bool              `json:"is_insensitive"`
	IsInboxTag        bool              `json:"is_inbox_tag"`
	DocumentCount     int64             `json:"document_count"`

	// Object owner; objects without owner can be viewed and edited by all users.
	Owner *int64 `json:"owner"`
}

type TagFields added in v0.0.5

type TagFields struct {
	// contains filtered or unexported fields
}

func NewTagFields added in v0.0.5

func NewTagFields() *TagFields

func (TagFields) AsMap added in v0.0.6

func (f TagFields) AsMap() map[string]any

AsMap returns a map from object field name to value.

func (TagFields) MarshalJSON added in v0.0.5

func (f TagFields) MarshalJSON() ([]byte, error)

func (*TagFields) SetColor added in v0.0.6

func (f *TagFields) SetColor(color Color) *TagFields

SetColor sets the "color" field.

func (*TagFields) SetIsInboxTag added in v0.0.6

func (f *TagFields) SetIsInboxTag(isInboxTag bool) *TagFields

SetIsInboxTag sets the "is_inbox_tag" field.

func (*TagFields) SetIsInsensitive added in v0.0.6

func (f *TagFields) SetIsInsensitive(isInsensitive bool) *TagFields

SetIsInsensitive sets the "is_insensitive" field.

func (*TagFields) SetMatch added in v0.0.6

func (f *TagFields) SetMatch(match string) *TagFields

SetMatch sets the "match" field.

func (*TagFields) SetMatchingAlgorithm added in v0.0.6

func (f *TagFields) SetMatchingAlgorithm(matchingAlgorithm MatchingAlgorithm) *TagFields

SetMatchingAlgorithm sets the "matching_algorithm" field.

func (*TagFields) SetName added in v0.0.6

func (f *TagFields) SetName(name string) *TagFields

SetName sets the "name" field.

func (*TagFields) SetOwner added in v0.0.6

func (f *TagFields) SetOwner(owner *int64) *TagFields

SetOwner sets the "owner" field.

Object owner; objects without owner can be viewed and edited by all users.

func (*TagFields) SetSetPermissions added in v0.0.6

func (f *TagFields) SetSetPermissions(setPermissions *ObjectPermissions) *TagFields

SetSetPermissions sets the "set_permissions" field.

Change object-level permissions.

func (*TagFields) SetTextColor added in v0.0.6

func (f *TagFields) SetTextColor(textColor Color) *TagFields

SetTextColor sets the "text_color" field.

type Task

type Task struct {
	ID           int64      `json:"id"`
	TaskID       string     `json:"task_id"`
	TaskFileName *string    `json:"task_file_name"`
	Created      *time.Time `json:"date_created"`
	Done         *time.Time `json:"date_done"`
	Type         string     `json:"type"`
	Status       TaskStatus `json:"status"`
	Result       *string    `json:"result"`
	Acknowledged bool       `json:"acknowledged"`
}

type TaskError

type TaskError struct {
	TaskID  string
	Status  TaskStatus
	Message string
}

func (*TaskError) Error

func (e *TaskError) Error() string

func (*TaskError) Is

func (e *TaskError) Is(other error) bool

type TaskStatus

type TaskStatus int
const (
	TaskStatusUnspecified TaskStatus = iota

	// Task is waiting for execution.
	TaskPending

	// Task has been started.
	TaskStarted

	// Task has been successfully executed.
	TaskSuccess

	// Task execution resulted in failure.
	TaskFailure

	// Task is being retried.
	TaskRetry

	// Task has been revoked.
	TaskRevoked
)

Celery task states (https://docs.celeryq.dev/en/latest/userguide/tasks.html#built-in-states).

func (TaskStatus) MarshalJSON

func (s TaskStatus) MarshalJSON() ([]byte, error)

func (TaskStatus) String

func (i TaskStatus) String() string

func (TaskStatus) Terminal

func (s TaskStatus) Terminal() bool

Terminal returns whether a task with the receiving status is finished permanently.

func (*TaskStatus) UnmarshalJSON

func (s *TaskStatus) UnmarshalJSON(data []byte) error

type TokenAuth

type TokenAuth struct {
	Token string
}

Paperless authentication token.

Example
ts := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
defer ts.Close()

cl := New(Options{
	BaseURL: ts.URL,
	Auth:    &TokenAuth{"mytoken1234"},
})

if err := cl.Ping(context.Background()); err != nil {
	fmt.Printf("Pinging server failed: %v\n", err)
} else {
	fmt.Println("Success!")
}
Output:

Success!

type User added in v0.0.6

type User struct {
	ID          int64  `json:"id"`
	Username    string `json:"username"`
	Email       string `json:"email"`
	FirstName   string `json:"first_name"`
	LastName    string `json:"last_name"`
	IsActive    bool   `json:"is_active"`
	IsStaff     bool   `json:"is_staff"`
	IsSuperuser bool   `json:"is_superuser"`
}

type UserFields added in v0.0.6

type UserFields struct {
	// contains filtered or unexported fields
}

func NewUserFields added in v0.0.6

func NewUserFields() *UserFields

func (UserFields) AsMap added in v0.0.6

func (f UserFields) AsMap() map[string]any

AsMap returns a map from object field name to value.

func (UserFields) MarshalJSON added in v0.0.6

func (f UserFields) MarshalJSON() ([]byte, error)

func (*UserFields) SetEmail added in v0.0.6

func (f *UserFields) SetEmail(email string) *UserFields

SetEmail sets the "email" field.

func (*UserFields) SetFirstName added in v0.0.6

func (f *UserFields) SetFirstName(firstName string) *UserFields

SetFirstName sets the "first_name" field.

func (*UserFields) SetIsActive added in v0.0.6

func (f *UserFields) SetIsActive(isActive bool) *UserFields

SetIsActive sets the "is_active" field.

func (*UserFields) SetIsStaff added in v0.0.6

func (f *UserFields) SetIsStaff(isStaff bool) *UserFields

SetIsStaff sets the "is_staff" field.

func (*UserFields) SetIsSuperuser added in v0.0.6

func (f *UserFields) SetIsSuperuser(isSuperuser bool) *UserFields

SetIsSuperuser sets the "is_superuser" field.

func (*UserFields) SetLastName added in v0.0.6

func (f *UserFields) SetLastName(lastName string) *UserFields

SetLastName sets the "last_name" field.

func (*UserFields) SetUsername added in v0.0.6

func (f *UserFields) SetUsername(username string) *UserFields

SetUsername sets the "username" field.

type UsernamePasswordAuth

type UsernamePasswordAuth struct {
	Username string
	Password string
}

HTTP basic authentication with a username and password.

type WaitForTaskConditionFunc

type WaitForTaskConditionFunc func(*Task) error

type WaitForTaskOptions

type WaitForTaskOptions struct {
	// Condition returns nil when the task is considered finished.
	// [DefaultWaitForTaskCondition] is the default implementation.
	Condition WaitForTaskConditionFunc

	// Maximum amount of time to wait. Defaults to one hour.
	MaxElapsedTime time.Duration
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL